flayr

[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}.)

[read-only] n per arm, pooled reach engagement rate, 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". (Wraps GET /api/v2/experiments/{id}/readout.)

[read-only] The experiment's posts split by its compareKey, with the leading variant by its primary metric and n per arm. Small samples: read medians with their n. (Wraps GET /api/v2/experiments/{id}/results.)

[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. (Wraps GET /api/v2/experiments/{id}/rounds.)

[read-only] One library frame with its sizes and content areas. (Wraps GET /api/v2/frames/{id}.)

[read-only] Which frame each platform's images get automatically when a post is published or scheduled. (Wraps GET /api/v2/frames/settings.)

[read-only] One trigger with its keywords, texts, link, cap and counts. (Wraps GET /api/v2/growth-triggers/{id}.)

[read-only] Matched comments, unique commenters, replies, DMs and failures, in total and per day. (Wraps GET /api/v2/growth-triggers/{id}/stats.)

[read-only] 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. (Wraps GET /api/v2/generate/status/{jobId}.)

[read-only] A post (`id` = convexPostId from publish, or posts[].id from get_content): status, slot, platforms, and while it is scheduled the first comment each platform will publish and whether it can be changed now. (Wraps GET /api/v2/posts/{id}.)

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

[read-only] One format (text template) with its full structure and example. (Wraps GET /api/v2/text-templates/{id}.)

[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). Existing sections and decisions are kept. (Wraps POST /api/v2/campaigns/{id}/review.)

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

[read-only] The brand's hook bank (filter by status: draft, approved, retired), with each hook's claims result. Free. Needs the Pro plan or higher. (Wraps GET /api/v2/hook-studio/hooks.)

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

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

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

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

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

[read-only] 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; a brand API key is created by the owner in Settings, never by an agent. (Wraps GET /api/v2/brands.)

[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) 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, and tell the user to reconnect any account that is not healthy at flayr.social/connect. (Wraps GET /api/v2/accounts.)

[read-only] Lists content items (drafts), newest first. Each carries `postState` ("posted" / "scheduled" / null) and `posts[]` (up to 5): where it went out, per platform, with status, live URL and failure reason. (Wraps GET /api/v2/content.)

[read-only] A/B experiments. Content joins one by carrying the label `experiment:<id>` plus `<compareKey>:<variant>`. (Wraps GET /api/v2/experiments.)

[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. Each has a `ref` to pass to apply_frame. (Wraps GET /api/v2/frames.)

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

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

[read-only] A post's comments-after-publish and reshares, with status (waiting, needs_approval, sent, failed) and the resolved text. (Wraps GET /api/v2/posts/{id}/comments.)

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

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

[read-only] Scheduled posts waiting for (or given) a human sign-off, oldest slot first. `canApprove` tells whether THIS connection may approve each one. (Wraps GET /api/v2/reviews.)

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

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

[read-only] Playlists of the YouTube channel(s) a brand publishes to. Use a playlist id as `youtube.playlistId` on create_content or publish. (Wraps GET /api/v2/youtube/playlists.)

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

[read-only] The brand's offer bank (filter by status: draft, confirmed, retired). Free. Needs the Pro plan or higher. (Wraps GET /api/v2/hook-studio/offers.)

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

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

[PUBLISHES to social accounts · `publish` scope] 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. 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). `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, or pass `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. T…

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

[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. Also `youtubeTitle`, per-item `platforms`, and `position` (0-based among waiting items). Needs the `publish` scope (or admin) on the Agency plan or higher. (Wraps PATCH /api/v2/queues/{id}/items/{itemId}.)

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

[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. 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. (Wraps POST /api/v2/video-studio/templates/motion-ad-from-card/render.)

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

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

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

[writes flayr data · `write` scope] Changes an experiment's fields (e.g. status "running" / "done", endAt, notes). Only the fields you pass change. (Wraps PATCH /api/v2/experiments/{id}.)

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

[PUBLISHES to social accounts · `publish` scope] 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. (Wraps PATCH /api/v2/growth-triggers/{id}.)