# 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).

## 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.
- 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

- 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).
- list_brands (read-only): Lists the brands this connection can file content into and publish through.
- 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) and whether flayr can post there right now (`postable`; Reddit is paused because Reddit closed its API to third-party apps).
- 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.
- upload_media (writes flayr data, `write` scope): Step 1 of attaching a LOCAL file (video or image) to a draft.
- list_content (read-only): Lists content items (drafts), newest first.
- 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.
- update_content (writes flayr data, `write` scope): Edits a draft in place; only the fields you pass change.
- 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).
- get_job_status (read-only): Status of an async job (combine_clips, or an API video generation): pending, processing, completed or failed.
- 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, 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.
- 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.
- 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: only the assigned approver may decide.
- 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.
- 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:<key>, 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.
- 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_share_rules (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.
- 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:<post id>}}, {{youtubeUrl:<post id>}}), 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).

## 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.

- GET /api/v2/ping — API liveness and key check
- GET /api/v2/content — List content
- POST /api/v2/content — Create content
- GET /api/v2/brands — List brands
- 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/analytics — Analytics overview
- GET /api/v2/brand/voices — Get default brand voice
- 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
- GET /api/v2/reviews — List scheduled-post reviews
- POST /api/v2/reviews/{id} — Approve or hold a scheduled post
- 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/approvals — List content waiting for your approval
- POST /api/v2/approvals/{id} — Approve or reject content held for approval
- 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
- 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/labels/taxonomy — Get the tag preset
- PUT /api/v2/labels/taxonomy — Replace the tag preset
- 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/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
- 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
- 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
- POST /api/v2/content/{id}/combine — Combine clips into a finished video (async)
- GET /api/v2/generate/status/{jobId} — Job status
- GET /api/v2/posts/{id} — Get a scheduled post's first comments
- PATCH /api/v2/posts/{id} — Edit a scheduled post (caption, first comments)
- DELETE /api/v2/posts/{id} — Cancel a scheduled post
- 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)