Create, schedule and publish social posts to 13 platforms for your brands.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
[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}.)
The server marks this tool as destructive. Running it may delete or overwrite data on the server or in any account you connected with your headers.
[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}.)
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| op* | string |
{
"type": "object",
"required": [
"id",
"op"
],
"properties": {
"id": {
"type": "string"
},
"op": {
"enum": [
"approve",
"reject",
"retry",
"cancel"
],
"type": "string"
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| comments* | array |
{
"type": "object",
"required": [
"id",
"comments"
],
"properties": {
"id": {
"type": "string"
},
"comments": {
"type": "array",
"items": {
"type": "object",
"required": [
"platform",
"text"
],
"properties": {
"text": {
"type": "string"
},
"sendAt": {
"type": "string",
"format": "date-time",
"description": "Not before this time."
},
"platform": {
"type": "string"
},
"accountId": {
"type": "string",
"description": "Default: the account the post went out through on that platform."
},
"delayMinutes": {
"type": "integer",
"minimum": 0
}
}
},
"maxItems": 20
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| items | array | |
| brandId | string | |
| contentIds | array |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"contentId"
],
"properties": {
"contentId": {
"type": "string"
},
"platforms": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Post this item to these platforms instead of the queue's."
},
"youtubeTitle": {
"type": "string",
"maxLength": 100,
"description": "The video's YouTube title. Omitted → the draft's stored title, else derived from its caption."
}
}
},
"maxItems": 200
},
"brandId": {
"type": "string"
},
"contentIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 200
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| fit | string | |
| zoom | number | |
| texts | object | Texts some frames print (ribbon/tag label, lower-third title/subtitle). |
| aspect | string | Default: nearest to the source image. |
| offsetX | number | |
| offsetY | number | |
| frameRef* | string | `default:<key>` or `brand:<id>` from GET /api/v2/frames. |
| platform | string | Platform this framed image is for ("all" by default). |
| contentId | string | A content id: its publish swaps this framed image in for `platform`. |
| sourceUrl |
[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}.)
| Argument | Type | Description |
|---|---|---|
| id* | string | The post: `convexPostId` from POST /api/v2/publish, or `posts[].id` from GET /api/v2/content/{id}. |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The post: `convexPostId` from POST /api/v2/publish, or `posts[].id` from GET /api/v2/content/{id}."
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| id* | string | The video to extend. |
| audio | string | |
| segments* | array | In playback order. Must include this video ({ "kind": "clip", "contentId": "<id>" }). |
| transition | string | |
| crossfadeMs | integer | Crossfade overlap per join. |
{
"type": "object",
"required": [
"id",
"segments"
],
"properties": {
"id": {
"type": "string",
"description": "The video to extend."
},
"audio": {
"enum": [
"keep",
"mute_extras",
"main_across"
],
"type": "string",
"default": "keep"
},
"segments": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind"
],
"properties": {
"inMs": {
"type": "integer",
"minimum": 0,
"description": "clip only: where the clip starts (default 0)."
},
"kind": {
"enum": [
"clip",
"card"
],
"type": "string"
},
"text": {
"type": "string",
"maxLength": 80,
"description": "card only: one short line over the image."
},
"outMs": {
"type": "integer",
"minimum": 0,
"description": "clip only: where the clip ends. Defaults to durationMs."
},
"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)."
},
"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)."
},
"imageStorageId": {
"type": "string",
"description": "card only: an uploaded image."
}
},
"additionalProperties": false
},
"maxItems": 8,
"minItems": 2,
"description": "In playback order. Must include this video ({ \"kind\": \"clip\", \"contentId\": \"<id>\" })."
},
"transition": {
"enum": [
"cut",
"crossfade"
],
"type": "string",
"default": "cut"
},
"crossfadeMs": {
"type": "integer",
"default": 400,
"maximum": 500,
"minimum": 300,
"description": "Crossfade overlap per join."
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| key | string | |
| metric | string | Which metric "leading" ranks by. |
| window | string | |
| brandId | string | A brand id, or "all" (default: every profile you can see). A brand-bound key is always its own brand. |
| include | string |
{
"type": "object",
"properties": {
"key": {
"type": "string",
"default": "cut"
},
"metric": {
"enum": [
"impressions",
"views",
"engagement",
"engagementRate",
"clicks"
],
"type": "string",
"default": "impressions",
"description": "Which metric \"leading\" ranks by."
},
"window": {
"enum": [
"48h",
"7d",
"latest"
],
"type": "string",
"default": "48h"
},
"brandId": {
"type": "string",
"description": "A brand id, or \"all\" (default: every profile you can see). A brand-bound key is always its own brand."
},
"include": {
"enum": [
"posts"
],
"type": "string"
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| text | string | |
| labels | array | 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. |
| brandId | string | An id from GET /api/v2/brands, or "personal". |
| credits | array | 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. |
| youtube | object | 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. |
[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.)
| Argument | Type | Description |
|---|---|---|
| name* | string | |
| endAt | string | null | |
| notes | string | |
| status | string | |
| brandId | string | A brand id, or "personal" (default). |
| startAt | string | null | |
| variants | array | |
| compareKey | string | |
| hypothesis | string | |
| primaryMetric | string |
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 120
},
"endAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"notes": {
"type": "string",
"maxLength": 2000
},
"status": {
"enum": [
"draft",
"running",
"done"
],
"type": "string"
},
"brandId": {
"type": "string",
"description": "A brand id, or \"personal\" (default)."
},
"startAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"variants": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 12
},
"compareKey": {
"type": "string"
},
"hypothesis": {
"type": "string",
"maxLength": 2000
},
"primaryMetric": {
"enum": [
"impressions",
"views",
"engagement",
"engagementRate",
"clicks"
],
"type": "string"
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| kind | string | Default: guessed from the name. |
| name | string | |
| tags | array | |
| texts | object | Texts some frames print (ribbon/tag label, lower-third title/subtitle). |
| rights | string | Who holds the rights to the art. Optional; a frame without it shows a reminder. |
| variants | array | One per aspect ratio. |
| defaultKey | string | A defaults[].ref without "default:". |
| paletteOverride | object | Colors that win over the brand kit. |
{
"type": "object",
"properties": {
"kind": {
"enum": [
"border",
"overlay",
"lower_third",
"corner_bug",
"quote_card",
"ribbon"
],
"type": "string",
"description": "Default: guessed from the name."
},
"name": {
"type": "string",
"maxLength": 80
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 20
},
"texts": {
"type": "object",
"properties": {
"label": {
"type": "string",
"maxLength": 60
},
"title": {
"type": "string",
"maxLength": 60
},
"subtitle": {
"type": "string",
"maxLength": 60
}
},
"description": "Texts some frames print (ribbon/tag label, lower-third title/subtitle)."
},
"rights": {
"enum": [
"original",
"owned",
"licensed"
],
"type": "string",
"description": "Who holds the rights to the art. Optional; a frame without it shows a reminder."
},
"variants": {
"type": "array",
"items": {
"type": "object",
"required": [
"storageId"
],
"properties": {
"fit": {
"enum": [
"cover",
"contain"
],
"type": "string"
},
"aspect": {
"enum": [
"1:1",
"4:5",
"9:16",
"16:9"
],
"type": "string",
"description": "Default: nearest to the image size."
},
"storageId": {
"type": "string",
"description": "From POST /api/v2/media/upload-url, then POST the PNG (with transparency) or SVG bytes."
},
"contentBox": {
"type": "object",
"required": [
"x",
"y",
"w",
"h"
],
"properties": {
"h": {
"type": "number"
},
"w": {
"type": "number"
},
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"description": "Default: detected from the transparent area. Where the post sits inside the frame, as fractions (0–1) of the frame canvas."
}
}
},
"maxItems": 4,
"minItems": 1,
"description": "One per aspect ratio."
},
"defaultKey": {
"type": "string",
"description": "A defaults[].ref without \"default:\"."
},
"paletteOverride": {
"type": "object",
"properties": {
"ink": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"paper": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"accent": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"primary": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"onPrimary": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"secondary": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
}
},
"description": "Colors that win over the brand kit."
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| name* | string | |
| brandId | string | |
| youtube | object | 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. |
| startsAt | string | 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. |
| timezone | string | IANA timezone. Slots keep their local time across DST. |
| lookahead |
[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.)
| Argument | Type | Description |
|---|---|---|
| kind | string | `reshare`: share the post to `targets`. `comment`: comment on the post itself through the source account. |
| name* | string | |
| brandId | string | |
| enabled | boolean | |
| targets | array | |
| approval | string | `needs_approval` (default): each fire waits for a person (POST …/actions/{id} `approve`). `auto`: runs on its own. |
| template | string | 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>}}`. |
[writes flayr data · `write` scope] Creates a reusable format (text template) in a brand. (Wraps POST /api/v2/text-templates.)
| Argument | Type | Description |
|---|---|---|
| name* | string | |
| format* | string | |
| length* | object | |
| source | string | null | Where the shape came from, e.g. an import path. |
| useFor | string | null | One line: when to pick this format. |
| brandId | string | |
| example | string | null | |
| ctaSlots | array | |
| platform | string | null | e.g. "linkedin"; null = any platform. |
| sections | array | In order. "Start from a format" writes one `[you fill: Label — guidance]` placeholder per section. |
[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. 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}.)
| Argument | Type | Description |
|---|---|---|
| id* | string | An approval id. |
| note | string | |
| decision* | string |
{
"type": "object",
"required": [
"id",
"decision"
],
"properties": {
"id": {
"type": "string",
"description": "An approval id."
},
"note": {
"type": "string",
"maxLength": 1000
},
"decision": {
"enum": [
"approve",
"reject"
],
"type": "string"
}
},
"additionalProperties": false
}[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}.)
| Argument | Type | Description |
|---|---|---|
| id* | string | A convexPostId or a review id. |
| note | string | |
| decision* | string | |
| pastSlot | any | Only for a held post whose slot passed: "now", or { at: ISO-8601 future time }. |
| collabSide | string | 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. |
{
"type": "object",
"required": [
"id",
"decision"
],
"properties": {
"id": {
"type": "string",
"description": "A convexPostId or a review id."
},
"note": {
"type": "string",
"maxLength": 1000
},
"decision": {
"enum": [
"approve",
"hold"
],
"type": "string"
},
"pastSlot": {
"oneOf": [
{
"enum": [
"now"
],
"type": "string"
},
{
"type": "object",
"required": [
"at"
],
"properties": {
"at": {
"type": "string",
"format": "date-time"
}
}
}
],
"description": "Only for a held post whose slot passed: \"now\", or { at: ISO-8601 future time }."
},
"collabSide": {
"enum": [
"owner",
"grantee"
],
"type": "string",
"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."
}
},
"additionalProperties": false
}[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}.)
| Argument | Type | Description |
|---|---|---|
| id* | string |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
}
},
"additionalProperties": false
}[DESTRUCTIVE] DESTRUCTIVE: deletes the experiment record (content keeps its labels). Ask the user before calling. (Wraps DELETE /api/v2/experiments/{id}.)
| Argument | Type | Description |
|---|---|---|
| id* | string |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
}
},
"additionalProperties": false
}[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}.)
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| brandId | string | Account-wide keys: "personal" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard). A brand-bound key always uses its own brand. |
| unschedule | boolean | 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. |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"brandId": {
"type": "string",
"description": "Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard). A brand-bound key always uses its own brand."
},
"unschedule": {
"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."
}
},
"additionalProperties": false
}[DESTRUCTIVE] DESTRUCTIVE: deletes a format (drafts started from it keep their text). Ask the user before calling. (Wraps DELETE /api/v2/text-templates/{id}.)
| Argument | Type | Description |
|---|---|---|
| id* | string |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
}
},
"additionalProperties": false
}[read-only] Engagement overview for the last 7, 30 or 90 days. Pro plan or higher. (Wraps GET /api/v2/analytics.)
| Argument | Type | Description |
|---|---|---|
| range | string |
{
"type": "object",
"properties": {
"range": {
"enum": [
"7d",
"30d",
"90d"
],
"type": "string",
"default": "30d"
}
},
"additionalProperties": false
}[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}.)
| Argument | Type | Description |
|---|---|---|
| id* | string |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
}
},
"additionalProperties": false
}[read-only] One experiment: hypothesis, variants, compareKey, window and status. (Wraps GET /api/v2/experiments/{id}.)
| Argument | Type | Description |
|---|---|---|
| id* | string |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| window | string | |
| include | string |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"window": {
"enum": [
"48h",
"7d",
"latest"
],
"type": "string",
"default": "48h"
},
"include": {
"enum": [
"posts"
],
"type": "string"
}
},
"additionalProperties": false
}[read-only] One library frame with its sizes and content areas. (Wraps GET /api/v2/frames/{id}.)
| Argument | Type | Description |
|---|---|---|
| id* | string |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
}
},
"additionalProperties": false
}[read-only] Which frame each platform's images get automatically when a post is published or scheduled. (Wraps GET /api/v2/frames/settings.)
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}[read-only] Status of an async job (combine_clips, or an API video generation): pending, processing, completed or failed. For a combine, `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}.)
| Argument | Type | Description |
|---|---|---|
| jobId* | string |
{
"type": "object",
"required": [
"jobId"
],
"properties": {
"jobId": {
"type": "string"
}
},
"additionalProperties": false
}[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}.)
| Argument | Type | Description |
|---|---|---|
| id* | string | The post: `convexPostId` from POST /api/v2/publish, or `posts[].id` from GET /api/v2/content/{id}. |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The post: `convexPostId` from POST /api/v2/publish, or `posts[].id` from GET /api/v2/content/{id}."
}
},
"additionalProperties": false
}[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}.)
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| brandId | string | Account-wide keys: "personal" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard). A brand-bound key always uses its own brand. |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"brandId": {
"type": "string",
"description": "Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard). A brand-bound key always uses its own brand."
}
},
"additionalProperties": false
}[read-only] One format (text template) with its full structure and example. (Wraps GET /api/v2/text-templates/{id}.)
| Argument | Type | Description |
|---|---|---|
| id* | string |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
}
},
"additionalProperties": false
}[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". Needs the explicit `approve` scope (admin does not include it). Agency plan. (Wraps GET /api/v2/approvals.)
| Argument | Type | Description |
|---|---|---|
| status | string | |
| brandId | string |
{
"type": "object",
"properties": {
"status": {
"enum": [
"pending"
],
"type": "string",
"default": "pending"
},
"brandId": {
"type": "string"
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| brandId | string | Account-wide keys: "personal" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard). A brand-bound key always uses its own brand. |
{
"type": "object",
"properties": {
"brandId": {
"type": "string",
"description": "Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard). A brand-bound key always uses its own brand."
}
},
"additionalProperties": false
}[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). (Wraps GET /api/v2/brands.)
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| brandId | string | An id from GET /api/v2/brands, or "personal". Omitted → the key's bound brand, else the owner's personal accounts. |
{
"type": "object",
"properties": {
"brandId": {
"type": "string",
"description": "An id from GET /api/v2/brands, or \"personal\". Omitted → the key's bound brand, else the owner's personal accounts."
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| brandId | string | A brand id from GET /api/v2/brands. Omitted: the key's brand (brand-bound key) or the owner's active brand. |
| includeArchived | boolean |
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"default": 20,
"maximum": 200,
"minimum": 1
},
"brandId": {
"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."
},
"includeArchived": {
"type": "boolean",
"default": false
}
},
"additionalProperties": false
}[read-only] A/B experiments. Content joins one by carrying the label `experiment:<id>` plus `<compareKey>:<variant>`. (Wraps GET /api/v2/experiments.)
| Argument | Type | Description |
|---|---|---|
| brandId | string | A brand id, or "all" (default: every profile you can see). A brand-bound key is always its own brand. |
| allBrands | boolean | 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. |
{
"type": "object",
"properties": {
"brandId": {
"type": "string",
"description": "A brand id, or \"all\" (default: every profile you can see). A brand-bound key is always its own brand."
},
"allBrands": {
"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."
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| kind | string | |
| aspect | string | |
| includeArchived | boolean |
{
"type": "object",
"properties": {
"kind": {
"enum": [
"border",
"overlay",
"lower_third",
"corner_bug",
"quote_card",
"ribbon"
],
"type": "string"
},
"aspect": {
"enum": [
"1:1",
"4:5",
"9:16",
"16:9"
],
"type": "string"
},
"includeArchived": {
"type": "boolean",
"default": false
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| brandId | string | An id from GET /api/v2/brands, or "personal". Omitted → the key's bound brand, else the owner's personal accounts. |
{
"type": "object",
"properties": {
"brandId": {
"type": "string",
"description": "An id from GET /api/v2/brands, or \"personal\". Omitted → the key's bound brand, else the owner's personal accounts."
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| id* | string |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| status | string | |
| brandId | string | Account-wide keys: "personal" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard). A brand-bound key always uses its own brand. |
{
"type": "object",
"properties": {
"status": {
"enum": [
"waiting",
"needs_approval",
"sending",
"sent",
"failed",
"cancelled",
"rejected"
],
"type": "string"
},
"brandId": {
"type": "string",
"description": "Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard). A brand-bound key always uses its own brand."
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| brandId | string | Account-wide keys: "personal" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard). A brand-bound key always uses its own brand. |
{
"type": "object",
"properties": {
"brandId": {
"type": "string",
"description": "Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard). A brand-bound key always uses its own brand."
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| status | string | |
| window | string | |
| brandId | string |
{
"type": "object",
"properties": {
"status": {
"enum": [
"pending",
"approved",
"held",
"missed",
"all"
],
"type": "string",
"default": "pending"
},
"window": {
"enum": [
"in",
"upcoming",
"all"
],
"type": "string",
"default": "all"
},
"brandId": {
"type": "string"
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| brandId | string | Account-wide keys: "personal" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard). A brand-bound key always uses its own brand. |
{
"type": "object",
"properties": {
"brandId": {
"type": "string",
"description": "Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard). A brand-bound key always uses its own brand."
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| brandId | string | 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. |
| includeArchived | boolean |
{
"type": "object",
"properties": {
"brandId": {
"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."
},
"includeArchived": {
"type": "boolean",
"default": false
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| brandId | string | An id from GET /api/v2/brands, or "personal". Omitted → the key's bound brand, else the owner's personal accounts. |
{
"type": "object",
"properties": {
"brandId": {
"type": "string",
"description": "An id from GET /api/v2/brands, or \"personal\". Omitted → the key's bound brand, else the owner's personal accounts."
}
},
"additionalProperties": false
}[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. `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. Then call get_content to see the live URLs. (Wraps POST /api/v2/publish.)
| Argument | Type | Description |
|---|---|---|
| memo | object | "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. |
[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.)
| Argument | Type | Description |
|---|---|---|
| dateTo | string | ISO date or epoch ms. Default: now. |
| format | string | 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. |
| metric | string | |
| window | string | Snapshot age: the metric as it stood 48h / 7d / 30d after publish, or the latest refresh. |
| brandId | string | A brand id, or "all" (default: every profile you can see). A brand-bound key is always its own brand. |
| filters | object | |
| formula | object | 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. |
[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}.)
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| action | string | |
| itemId* | string | |
| brandId | string | |
| position | integer | 0-based index among the waiting (queued) items. |
| platforms | array | null | 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). |
| youtubeTitle | string | null | null or "" → back to the draft's stored title. |
{
"type": "object",
"required": [
"id",
"itemId"
],
"properties": {
"id": {
"type": "string"
},
"action": {
"enum": [
"skip",
"retry",
"unschedule"
],
"type": "string"
},
"itemId": {
"type": "string"
},
"brandId": {
"type": "string"
},
"position": {
"type": "integer",
"minimum": 0,
"description": "0-based index among the waiting (queued) items."
},
"platforms": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"minItems": 1,
"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)."
},
"youtubeTitle": {
"type": [
"string",
"null"
],
"maxLength": 100,
"description": "null or \"\" → back to the draft's stored title."
}
},
"additionalProperties": false
}[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}.)
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| itemId* | string | |
| brandId | string | Account-wide keys: "personal" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard). A brand-bound key always uses its own brand. |
| unschedule | boolean | 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. |
{
"type": "object",
"required": [
"id",
"itemId"
],
"properties": {
"id": {
"type": "string"
},
"itemId": {
"type": "string"
},
"brandId": {
"type": "string",
"description": "Account-wide keys: \"personal\" or an id from GET /api/v2/brands (omitted → the brand last active in the dashboard). A brand-bound key always uses its own brand."
},
"unschedule": {
"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."
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| brandId | string | |
| itemIds* | array |
{
"type": "object",
"required": [
"id",
"itemIds"
],
"properties": {
"id": {
"type": "string"
},
"brandId": {
"type": "string"
},
"itemIds": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}[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` and `videoWatermarked` may be changed on published items too. 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}.)
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| opus | object | null | 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. |
| text | string | |
| title | string | Shorthand for youtube.title (the video title). No < or >. |
| images | array | Carousel image URLs. Cannot be combined with the other media fields. |
| labels | array | null | 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. |
[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}.)
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| name | string | |
| endAt | string | null | |
| notes | string | |
| status | string | |
| startAt | string | null | |
| variants | array | |
| compareKey | string | |
| hypothesis | string | |
| primaryMetric | string |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string",
"maxLength": 120
},
"endAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"notes": {
"type": "string",
"maxLength": 2000
},
"status": {
"enum": [
"draft",
"running",
"done"
],
"type": "string"
},
"startAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"variants": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 12
},
"compareKey": {
"type": "string"
},
"hypothesis": {
"type": "string",
"maxLength": 2000
},
"primaryMetric": {
"enum": [
"impressions",
"views",
"engagement",
"engagementRate",
"clicks"
],
"type": "string"
}
},
"additionalProperties": false
}[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.)
| Argument | Type | Description |
|---|---|---|
| aspect | string | |
| frameRef* | string | null | |
| platform* | string |
{
"type": "object",
"required": [
"platform",
"frameRef"
],
"properties": {
"aspect": {
"enum": [
"1:1",
"4:5",
"9:16",
"16:9"
],
"type": "string"
},
"frameRef": {
"type": [
"string",
"null"
]
},
"platform": {
"type": "string"
}
},
"additionalProperties": false
}[PUBLISHES to social accounts · `publish` scope] `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. (Wraps PATCH /api/v2/queues/{id}.)
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| name | string | |
| status | string | |
| brandId | string | |
| startsAt | string | null | 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. |
| lookahead | integer | |
| platforms | array | Replaces the queue's platforms for items booked from now on. Already-booked items keep theirs; items with their own `platforms` keep using them. |
| timeOfDay | string | 24-hour "HH:MM" local time. |
[PUBLISHES to social accounts · `publish` scope] 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). 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. (Wraps PATCH /api/v2/posts/{id}.)
| Argument | Type | Description |
|---|---|---|
| id* | string | The post: `convexPostId` from POST /api/v2/publish, or `posts[].id` from GET /api/v2/content/{id}. |
| text | string | The caption (every platform without its own). |
| firstComment | object | 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. |
| platformText | object | null |
[writes flayr data · `write` scope] Changes a format; only the fields you pass change. `archived: true` hides it. (Wraps PATCH /api/v2/text-templates/{id}.)
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| name | string | |
| format | string | |
| length | object | |
| source | string | null | Where the shape came from, e.g. an import path. |
| useFor | string | null | One line: when to pick this format. |
| example | string | null | |
| archived | boolean | |
| ctaSlots | array | |
| platform | string | null | e.g. "linkedin"; null = any platform. |
| sections | array | In order. "Start from a format" writes one `[you fill: Label — guidance]` placeholder per section. |
[writes flayr data · `write` scope] Step 1 of attaching a LOCAL file (video or image) 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 media already on the web, skip this and pass `videoUrl` / `imageUrl` instead. Returns 413 when the account's storage is full. (Wraps POST /api/v2/media/upload-url.)
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}[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). Call this first to learn what the connection can reach. (Wraps GET /api/v2/ping.)
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}| string |
| https image URL (flayr/Convex storage or a stock host). |
| slideIndex | integer | Image position in the post. |
| paletteOverride | object | Colors that win over the brand kit. |
{
"type": "object",
"required": [
"sourceUrl",
"frameRef"
],
"properties": {
"fit": {
"enum": [
"cover",
"contain"
],
"type": "string"
},
"zoom": {
"type": "number",
"maximum": 2,
"minimum": 1
},
"texts": {
"type": "object",
"properties": {
"label": {
"type": "string",
"maxLength": 60
},
"title": {
"type": "string",
"maxLength": 60
},
"subtitle": {
"type": "string",
"maxLength": 60
}
},
"description": "Texts some frames print (ribbon/tag label, lower-third title/subtitle)."
},
"aspect": {
"enum": [
"1:1",
"4:5",
"9:16",
"16:9"
],
"type": "string",
"description": "Default: nearest to the source image."
},
"offsetX": {
"type": "number",
"maximum": 1,
"minimum": -1
},
"offsetY": {
"type": "number",
"maximum": 1,
"minimum": -1
},
"frameRef": {
"type": "string",
"description": "`default:<key>` or `brand:<id>` from GET /api/v2/frames."
},
"platform": {
"type": "string",
"description": "Platform this framed image is for (\"all\" by default)."
},
"contentId": {
"type": "string",
"description": "A content id: its publish swaps this framed image in for `platform`."
},
"sourceUrl": {
"type": "string",
"description": "https image URL (flayr/Convex storage or a stock host)."
},
"slideIndex": {
"type": "integer",
"minimum": 0,
"description": "Image position in the post."
},
"paletteOverride": {
"type": "object",
"properties": {
"ink": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"paper": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"accent": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"primary": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"onPrimary": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"secondary": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
}
},
"description": "Colors that win over the brand kit."
}
},
"additionalProperties": false
}| imageUrl | string |
| videoUrl | string |
| platforms | array |
| contentType | string |
| sourceLabel | string |
| platformText | object | 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. |
| imageStorageId | string |
| referralFooter | boolean | 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. |
| videoStorageId | string |
| copyFromContentId | string | 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. |
{
"type": "object",
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"minLength": 1
},
"labels": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,31}:[a-z0-9][a-z0-9._\\-/+]{0,79}$"
},
"maxItems": 30,
"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."
},
"brandId": {
"type": "string",
"description": "An id from GET /api/v2/brands, or \"personal\"."
},
"credits": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "Absolute http(s) link to the credited work."
},
"kind": {
"enum": [
"model",
"music",
"footage",
"image",
"other"
],
"type": "string"
},
"site": {
"type": "string",
"maxLength": 200,
"description": "Detected from the URL when omitted (e.g. MakerWorld, Printables, Thingiverse)."
},
"title": {
"type": "string",
"maxLength": 200
},
"author": {
"type": "string",
"maxLength": 200,
"description": "Designer / artist / photographer."
}
},
"additionalProperties": false
},
"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."
},
"youtube": {
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 100
},
"description": "At most 500 characters combined."
},
"title": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "No < or >."
},
"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."
},
"visibility": {
"enum": [
"public",
"private",
"unlisted"
],
"type": "string",
"default": "public"
},
"madeForKids": {
"type": "boolean",
"default": false
},
"firstComment": {
"type": "string",
"maxLength": 10000,
"description": "For scheduled videos, posted at the scheduled time."
},
"containsSyntheticMedia": {
"type": "boolean",
"description": "AI-generated content disclosure."
}
},
"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."
},
"imageUrl": {
"type": "string"
},
"videoUrl": {
"type": "string"
},
"platforms": {
"type": "array",
"items": {
"type": "string"
}
},
"contentType": {
"type": "string"
},
"sourceLabel": {
"type": "string",
"maxLength": 80
},
"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",
"null"
],
"maxLength": 10000
}
},
"imageStorageId": {
"type": "string"
},
"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."
},
"videoStorageId": {
"type": "string"
},
"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."
}
},
"additionalProperties": false
}| integer |
| How many upcoming items are scheduled at the platform at once. |
| platforms* | array |
| timeOfDay | string | 24-hour "HH:MM" local time. |
| cadenceHours | integer | 1, 2, 3, 4, 6, 8, 12, or whole days (24, 48, …, 720). |
{
"type": "object",
"required": [
"name",
"platforms"
],
"properties": {
"name": {
"type": "string",
"maxLength": 80
},
"brandId": {
"type": "string"
},
"youtube": {
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 100
},
"description": "At most 500 characters combined."
},
"title": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "No < or >."
},
"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."
},
"visibility": {
"enum": [
"public",
"private",
"unlisted"
],
"type": "string",
"default": "public"
},
"madeForKids": {
"type": "boolean",
"default": false
},
"firstComment": {
"type": "string",
"maxLength": 10000,
"description": "For scheduled videos, posted at the scheduled time."
},
"containsSyntheticMedia": {
"type": "boolean",
"description": "AI-generated content disclosure."
}
},
"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."
},
"startsAt": {
"type": "string",
"format": "date-time",
"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."
},
"timezone": {
"type": "string",
"default": "America/Chicago",
"description": "IANA timezone. Slots keep their local time across DST."
},
"lookahead": {
"type": "integer",
"default": 2,
"maximum": 10,
"minimum": 1,
"description": "How many upcoming items are scheduled at the platform at once."
},
"platforms": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"timeOfDay": {
"type": "string",
"default": "19:00",
"description": "24-hour \"HH:MM\" local time."
},
"cadenceHours": {
"type": "integer",
"default": 24,
"description": "1, 2, 3, 4, 6, 8, 12, or whole days (24, 48, …, 720)."
}
},
"additionalProperties": false
}| sourceLabel | string | null | Only posts carrying this label. |
| delayMinutes | integer |
| sourceAccountIds* | array | Fires when a post goes live through any of these connected accounts. |
{
"type": "object",
"required": [
"name",
"sourceAccountIds"
],
"properties": {
"kind": {
"enum": [
"reshare",
"comment"
],
"type": "string",
"default": "reshare",
"description": "`reshare`: share the post to `targets`. `comment`: comment on the post itself through the source account."
},
"name": {
"type": "string",
"maxLength": 120
},
"brandId": {
"type": "string"
},
"enabled": {
"type": "boolean",
"default": true
},
"targets": {
"type": "array",
"items": {
"type": "object",
"required": [
"accountId",
"platform"
],
"properties": {
"platform": {
"type": "string"
},
"accountId": {
"type": "string"
}
}
}
},
"approval": {
"enum": [
"needs_approval",
"auto"
],
"type": "string",
"default": "needs_approval",
"description": "`needs_approval` (default): each fire waits for a person (POST …/actions/{id} `approve`). `auto`: runs on its own."
},
"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>}}`."
},
"sourceLabel": {
"type": [
"string",
"null"
],
"description": "Only posts carrying this label."
},
"delayMinutes": {
"type": "integer",
"default": 0,
"minimum": 0
},
"sourceAccountIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Fires when a post goes live through any of these connected accounts."
}
},
"additionalProperties": false
}| guardrails |
| array |
| maxHashtags | integer | null |
| hookPatterns | array | "[slot]" placeholders are kept as written. |
| defaultLabels | array | "key:value" labels every draft started from this format gets (plus the format's own `label`). |
{
"type": "object",
"required": [
"name",
"format",
"length"
],
"properties": {
"name": {
"type": "string",
"maxLength": 120
},
"format": {
"enum": [
"post",
"article",
"carousel_script",
"meme",
"thread"
],
"type": "string"
},
"length": {
"type": "object",
"required": [
"unit",
"min",
"max"
],
"properties": {
"max": {
"type": "integer",
"minimum": 1
},
"min": {
"type": "integer",
"minimum": 0
},
"unit": {
"enum": [
"words",
"chars",
"slides"
],
"type": "string"
},
"captionWords": {
"type": "object",
"properties": {
"max": {
"type": "integer"
},
"min": {
"type": "integer"
}
},
"description": "carousel_script: the caption that goes with the slides."
},
"titleMaxWords": {
"type": "integer",
"description": "carousel_script: words allowed in the title (first line of slide 1)."
},
"perSlideMaxWords": {
"type": "integer",
"description": "carousel_script / thread: words allowed per slide or post."
}
}
},
"source": {
"type": [
"string",
"null"
],
"maxLength": 200,
"description": "Where the shape came from, e.g. an import path."
},
"useFor": {
"type": [
"string",
"null"
],
"maxLength": 300,
"description": "One line: when to pick this format."
},
"brandId": {
"type": "string"
},
"example": {
"type": [
"string",
"null"
],
"maxLength": 20000
},
"ctaSlots": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"text": {
"type": "string"
},
"label": {
"type": "string"
},
"placement": {
"enum": [
"body",
"first_comment",
"none"
],
"type": "string",
"default": "body"
}
}
},
"maxItems": 10
},
"platform": {
"type": [
"string",
"null"
],
"description": "e.g. \"linkedin\"; null = any platform."
},
"sections": {
"type": "array",
"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
},
"maxLines": {
"type": "integer"
},
"minLines": {
"type": "integer"
},
"required": {
"type": "boolean",
"default": true
}
}
},
"maxItems": 20,
"description": "In order. \"Start from a format\" writes one `[you fill: Label — guidance]` placeholder per section."
},
"guardrails": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"maxItems": 30
},
"maxHashtags": {
"type": [
"integer",
"null"
],
"maximum": 30,
"minimum": 0
},
"hookPatterns": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300
},
"maxItems": 20,
"description": "\"[slot]\" placeholders are kept as written."
},
"defaultLabels": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 30,
"description": "\"key:value\" labels every draft started from this format gets (plus the format's own `label`)."
}
},
"additionalProperties": false
}| poll | object | 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. |
| labels | array | 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. |
| brandId | string | An id from GET /api/v2/brands, or "personal". With contentId it must match the item's brand. |
| content | string | Post text. Required unless contentId is given. |
| reshare | object | 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. |
| youtube | object | 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. |
| object | 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. |
| imageUrl | string |
| videoUrl | string |
| contentId | string | An existing content item id (GET /api/v2/content/{id} access rules). Cannot be combined with imageUrl / videoUrl. |
| object | 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. |
| object | 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. |
| platforms* | array |
| aiGenerated | boolean | 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. |
| scheduledAt | string | Must be in the future. Omitted → publish now. |
| firstComment | object | 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. |
| idempotencyKey | string | Unique per API key. A retry with the same key never posts twice. |
| onPublishTasks | array | Shorthand for memo.tasks (appended after them). Response: `memoId`; a memo that could not be saved is a `warnings` entry, never a failed publish. |
| referralFooter | boolean | 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. |
| mediaCampaignId | string | Link to a media campaign; with a brand target it must belong to that brand. |
| autoFirstComment | boolean | 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. |
| followUpComments | array | 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. |
| requiresApproval | boolean |
| allowDuplicateBooking | boolean | 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. |
{
"type": "object",
"required": [
"platforms"
],
"properties": {
"memo": {
"type": "object",
"properties": {
"notes": {
"type": "string",
"maxLength": 4000
},
"tasks": {
"type": "array",
"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."
},
"url": {
"type": "string",
"format": "uri",
"description": "Where to do it (http/https)."
},
"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\"."
}
}
}
]
},
"maxItems": 30
}
},
"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."
},
"poll": {
"type": "object",
"required": [
"options"
],
"properties": {
"options": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 10,
"minItems": 2
},
"question": {
"type": "string",
"maxLength": 300
},
"durationMinutes": {
"type": "integer",
"default": 1440,
"minimum": 5
}
},
"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.",
"additionalProperties": false
},
"labels": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,31}:[a-z0-9][a-z0-9._\\-/+]{0,79}$"
},
"maxItems": 30,
"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."
},
"brandId": {
"type": "string",
"description": "An id from GET /api/v2/brands, or \"personal\". With contentId it must match the item's brand."
},
"content": {
"type": "string",
"maxLength": 10000,
"minLength": 1,
"description": "Post text. Required unless contentId is given."
},
"reshare": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"postId": {
"type": "string"
}
},
"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.",
"additionalProperties": false
},
"youtube": {
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 100
},
"description": "At most 500 characters combined."
},
"title": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "No < or >."
},
"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."
},
"visibility": {
"enum": [
"public",
"private",
"unlisted"
],
"type": "string",
"default": "public"
},
"madeForKids": {
"type": "boolean",
"default": false
},
"firstComment": {
"type": "string",
"maxLength": 10000,
"description": "For scheduled videos, posted at the scheduled time."
},
"containsSyntheticMedia": {
"type": "boolean",
"description": "AI-generated content disclosure."
}
},
"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."
},
"facebook": {
"type": "object",
"properties": {
"contentType": {
"enum": [
"reel",
"story",
"feed"
],
"type": "string"
}
},
"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.",
"additionalProperties": false
},
"imageUrl": {
"type": "string"
},
"videoUrl": {
"type": "string"
},
"contentId": {
"type": "string",
"description": "An existing content item id (GET /api/v2/content/{id} access rules). Cannot be combined with imageUrl / videoUrl."
},
"instagram": {
"type": "object",
"properties": {
"contentType": {
"enum": [
"reel",
"story",
"feed"
],
"type": "string"
}
},
"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.",
"additionalProperties": false
},
"pinterest": {
"type": "object",
"properties": {
"link": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "Destination link (http or https)."
},
"title": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"boardId": {
"type": "string",
"maxLength": 200,
"description": "From GET /api/v2/pinterest/boards for the same brand."
}
},
"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.",
"additionalProperties": false
},
"platforms": {
"type": "array",
"items": {
"enum": [
"instagram",
"tiktok",
"youtube",
"youtube_shorts",
"linkedin",
"pinterest",
"twitter",
"facebook",
"threads",
"bluesky",
"snapchat",
"googlebusiness",
"google_business",
"reddit",
"telegram",
"discord"
],
"type": "string"
},
"maxItems": 10,
"minItems": 1
},
"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."
},
"scheduledAt": {
"type": "string",
"format": "date-time",
"description": "Must be in the future. Omitted → publish now."
},
"firstComment": {
"type": "object",
"properties": {
"threads": {
"type": "string",
"maxLength": 500
},
"facebook": {
"type": "string",
"maxLength": 8000
},
"linkedin": {
"type": "string",
"maxLength": 1250
},
"instagram": {
"type": "string",
"maxLength": 2200
}
},
"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.",
"additionalProperties": false
},
"idempotencyKey": {
"type": "string",
"maxLength": 200,
"description": "Unique per API key. A retry with the same key never posts twice."
},
"onPublishTasks": {
"type": "array",
"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."
},
"url": {
"type": "string",
"format": "uri",
"description": "Where to do it (http/https)."
},
"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\"."
}
}
}
]
},
"maxItems": 30,
"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."
},
"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."
},
"mediaCampaignId": {
"type": "string",
"description": "Link to a media campaign; with a brand target it must belong to that brand."
},
"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."
},
"followUpComments": {
"type": "array",
"items": {
"type": "object",
"required": [
"platform",
"text"
],
"properties": {
"text": {
"type": "string"
},
"sendAt": {
"type": "string",
"format": "date-time"
},
"platform": {
"type": "string"
},
"delayMinutes": {
"type": "integer",
"minimum": 0
}
}
},
"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."
},
"requiresApproval": {
"type": "boolean",
"default": false
},
"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."
}
},
"additionalProperties": false
}| dateFrom | string | ISO date or epoch ms (publish time). Default: 90 days ago; ranges are capped at 400 days. |
| interval | string | Adds a time series bucketed by publish date. |
| breakdown | array | 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 (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. |
| aggregation | string | 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. |
| tzOffsetMinutes | integer | Offset from UTC for weekday / hour / day buckets (e.g. -300). |
{
"type": "object",
"properties": {
"dateTo": {
"type": "string",
"description": "ISO date or epoch ms. Default: now."
},
"format": {
"enum": [
"json",
"csv"
],
"type": "string",
"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."
},
"metric": {
"enum": [
"impressions",
"views",
"engagement",
"engagementRate",
"clicks",
"ctr",
"reach",
"likes",
"comments",
"shares",
"saves",
"followersGained",
"watchTimeHours",
"avgWatchSeconds",
"completionRate",
"postsPublished",
"referralClicks"
],
"type": "string",
"default": "impressions"
},
"window": {
"enum": [
"48h",
"7d",
"30d",
"lifetime"
],
"type": "string",
"default": "7d",
"description": "Snapshot age: the metric as it stood 48h / 7d / 30d after publish, or the latest refresh."
},
"brandId": {
"type": "string",
"description": "A brand id, or \"all\" (default: every profile you can see). A brand-bound key is always its own brand."
},
"filters": {
"type": "object",
"properties": {
"labels": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 5,
"description": "Every label must be on the post (key:value)."
},
"platforms": {
"type": "array",
"items": {
"type": "string"
}
},
"campaignId": {
"type": "string"
},
"experimentId": {
"type": "string",
"description": "Reads the experiment over its own start–end window."
},
"excludeLabels": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 5,
"description": "Posts with any of these labels are left out (the tag templates exclude line:test)."
}
}
},
"formula": {
"type": "object",
"required": [
"series",
"expression"
],
"properties": {
"format": {
"enum": [
"number",
"percent"
],
"type": "string",
"default": "number",
"description": "percent = a ratio shown ×100 with a % sign."
},
"series": {
"type": "object",
"required": [
"A"
],
"properties": {
"A": {
"type": "object",
"required": [
"metric"
],
"properties": {
"metric": {
"enum": [
"impressions",
"views",
"engagement",
"engagementRate",
"clicks",
"ctr",
"reach",
"likes",
"comments",
"shares",
"saves",
"followersGained",
"watchTimeHours",
"avgWatchSeconds",
"completionRate",
"postsPublished",
"referralClicks"
],
"type": "string"
},
"aggregation": {
"enum": [
"sum",
"mean",
"median",
"p90",
"count",
"pooled"
],
"type": "string"
}
}
},
"B": {
"type": "object",
"required": [
"metric"
],
"properties": {
"metric": {
"enum": [
"impressions",
"views",
"engagement",
"engagementRate",
"clicks",
"ctr",
"reach",
"likes",
"comments",
"shares",
"saves",
"followersGained",
"watchTimeHours",
"avgWatchSeconds",
"completionRate",
"postsPublished",
"referralClicks"
],
"type": "string"
},
"aggregation": {
"enum": [
"sum",
"mean",
"median",
"p90",
"count",
"pooled"
],
"type": "string"
}
}
},
"C": {
"type": "object",
"required": [
"metric"
],
"properties": {
"metric": {
"enum": [
"impressions",
"views",
"engagement",
"engagementRate",
"clicks",
"ctr",
"reach",
"likes",
"comments",
"shares",
"saves",
"followersGained",
"watchTimeHours",
"avgWatchSeconds",
"completionRate",
"postsPublished",
"referralClicks"
],
"type": "string"
},
"aggregation": {
"enum": [
"sum",
"mean",
"median",
"p90",
"count",
"pooled"
],
"type": "string"
}
}
}
}
},
"expression": {
"type": "string",
"maxLength": 80
}
},
"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."
},
"dateFrom": {
"type": "string",
"description": "ISO date or epoch ms (publish time). Default: 90 days ago; ranges are capped at 400 days."
},
"interval": {
"enum": [
"day",
"week",
"month"
],
"type": "string",
"description": "Adds a time series bucketed by publish date."
},
"breakdown": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 2,
"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 (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."
},
"aggregation": {
"enum": [
"sum",
"mean",
"median",
"p90",
"count",
"pooled"
],
"type": "string",
"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."
},
"tzOffsetMinutes": {
"type": "integer",
"description": "Offset from UTC for weekday / hour / day buckets (e.g. -300)."
}
},
"additionalProperties": false
}| credits | array | null | 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. |
| youtube | object | 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. |
| imageUrl | string | http(s) image URL: the video's thumbnail, or on its own the post's single image. Not with imageStorageId. |
| videoUrl | string | http(s) URL of the new video. Not with videoStorageId. |
| platforms | array |
| platformText | object | null | 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. |
| thumbnailUrl | string | null | Custom video thumbnail: an http(s) image URL. Not with thumbnailStorageId. null clears. |
| imageStorageId | string | Uploaded image storageId: the video's thumbnail, or on its own the post's single image. Not with imageUrl. |
| videoStorageId | string | storageId from uploading to POST /api/v2/media/upload-url's uploadUrl. Not with videoUrl. Another account's upload is refused (422). |
| videoWatermarked | object | null | The item's own video already has the "Posted by flayr.social" watermark: publish it as-is. null clears. |
| thumbnailStorageId | string | null | Custom video thumbnail: an image storageId from POST /api/v2/media/upload-url. Not with thumbnailUrl. null clears. |
| thumbnailFrameOffsetMs | integer | 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. |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"opus": {
"type": [
"object",
"null"
],
"required": [
"clipId"
],
"properties": {
"clipId": {
"type": "string",
"description": "Opus clip id: the full \"{projectId}.{curationId}\" or the short curation id with projectId."
},
"projectId": {
"type": "string",
"description": "Opus project id. Optional when clipId is the full \"{projectId}.{clipId}\" id."
}
},
"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.",
"additionalProperties": false
},
"text": {
"type": "string",
"maxLength": 10000,
"minLength": 1
},
"title": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Shorthand for youtube.title (the video title). No < or >."
},
"images": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"maxItems": 20,
"minItems": 2,
"description": "Carousel image URLs. Cannot be combined with the other media fields."
},
"labels": {
"type": [
"array",
"null"
],
"items": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9_-]{0,31}:[a-z0-9][a-z0-9._\\-/+]{0,79}$"
},
"maxItems": 30,
"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."
},
"credits": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"required": [
"kind",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "Absolute http(s) link to the credited work."
},
"kind": {
"enum": [
"model",
"music",
"footage",
"image",
"other"
],
"type": "string"
},
"site": {
"type": "string",
"maxLength": 200,
"description": "Detected from the URL when omitted (e.g. MakerWorld, Printables, Thingiverse)."
},
"title": {
"type": "string",
"maxLength": 200
},
"author": {
"type": "string",
"maxLength": 200,
"description": "Designer / artist / photographer."
}
},
"additionalProperties": false
},
"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."
},
"youtube": {
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 100
},
"description": "At most 500 characters combined."
},
"title": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "No < or >."
},
"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."
},
"visibility": {
"enum": [
"public",
"private",
"unlisted"
],
"type": "string",
"default": "public"
},
"madeForKids": {
"type": "boolean",
"default": false
},
"firstComment": {
"type": "string",
"maxLength": 10000,
"description": "For scheduled videos, posted at the scheduled time."
},
"containsSyntheticMedia": {
"type": "boolean",
"description": "AI-generated content disclosure."
}
},
"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."
},
"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."
},
"videoUrl": {
"type": "string",
"format": "uri",
"description": "http(s) URL of the new video. Not with videoStorageId."
},
"platforms": {
"type": "array",
"items": {
"type": "string"
}
},
"platformText": {
"type": [
"object",
"null"
],
"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",
"null"
],
"maxLength": 10000
}
},
"thumbnailUrl": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Custom video thumbnail: an http(s) image URL. Not with thumbnailStorageId. null clears."
},
"imageStorageId": {
"type": "string",
"description": "Uploaded image storageId: the video's thumbnail, or on its own the post's single image. Not with imageUrl."
},
"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)."
},
"videoWatermarked": {
"type": [
"object",
"null"
],
"required": [
"version"
],
"properties": {
"at": {
"type": "integer",
"description": "When it was watermarked (epoch ms). Default: now."
},
"version": {
"type": "integer",
"maximum": 1,
"minimum": 1
}
},
"description": "The item's own video already has the \"Posted by flayr.social\" watermark: publish it as-is. null clears.",
"additionalProperties": false
},
"thumbnailStorageId": {
"type": [
"string",
"null"
],
"description": "Custom video thumbnail: an image storageId from POST /api/v2/media/upload-url. Not with thumbnailUrl. null clears."
},
"thumbnailFrameOffsetMs": {
"type": "integer",
"maximum": 86400000,
"minimum": 0,
"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."
}
},
"additionalProperties": false
}| cadenceHours | integer | 1, 2, 3, 4, 6, 8, 12, or whole days (24, 48, …, 720). |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string",
"maxLength": 80
},
"status": {
"enum": [
"active",
"paused"
],
"type": "string"
},
"brandId": {
"type": "string"
},
"startsAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"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."
},
"lookahead": {
"type": "integer",
"maximum": 10,
"minimum": 1
},
"platforms": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"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."
},
"timeOfDay": {
"type": "string",
"description": "24-hour \"HH:MM\" local time."
},
"cadenceHours": {
"type": "integer",
"description": "1, 2, 3, 4, 6, 8, 12, or whole days (24, 48, …, 720)."
}
},
"additionalProperties": false
}| Per-platform captions, merged into the draft's: { "linkedin": "…" } sets one, null / "" clears it; null clears them all. |
| removePlatforms | array | 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. |
| applyAutoFirstComment | boolean | Add the brand's auto first comment where the post has none. |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The post: `convexPostId` from POST /api/v2/publish, or `posts[].id` from GET /api/v2/content/{id}."
},
"text": {
"type": "string",
"maxLength": 10000,
"minLength": 1,
"description": "The caption (every platform without its own)."
},
"firstComment": {
"type": "object",
"properties": {
"threads": {
"type": [
"string",
"null"
],
"maxLength": 500
},
"youtube": {
"type": [
"string",
"null"
],
"maxLength": 10000
},
"facebook": {
"type": [
"string",
"null"
],
"maxLength": 8000
},
"linkedin": {
"type": [
"string",
"null"
],
"maxLength": 1250
},
"instagram": {
"type": [
"string",
"null"
],
"maxLength": 2200
}
},
"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.",
"minProperties": 1,
"additionalProperties": false
},
"platformText": {
"type": [
"object",
"null"
],
"description": "Per-platform captions, merged into the draft's: { \"linkedin\": \"…\" } sets one, null / \"\" clears it; null clears them all.",
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"removePlatforms": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"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."
},
"applyAutoFirstComment": {
"type": "boolean",
"description": "Add the brand's auto first comment where the post has none."
}
},
"additionalProperties": false
}| guardrails | array |
| maxHashtags | integer | null |
| hookPatterns | array | "[slot]" placeholders are kept as written. |
| defaultLabels | array | "key:value" labels every draft started from this format gets (plus the format's own `label`). |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string",
"maxLength": 120
},
"format": {
"enum": [
"post",
"article",
"carousel_script",
"meme",
"thread"
],
"type": "string"
},
"length": {
"type": "object",
"required": [
"unit",
"min",
"max"
],
"properties": {
"max": {
"type": "integer",
"minimum": 1
},
"min": {
"type": "integer",
"minimum": 0
},
"unit": {
"enum": [
"words",
"chars",
"slides"
],
"type": "string"
},
"captionWords": {
"type": "object",
"properties": {
"max": {
"type": "integer"
},
"min": {
"type": "integer"
}
},
"description": "carousel_script: the caption that goes with the slides."
},
"titleMaxWords": {
"type": "integer",
"description": "carousel_script: words allowed in the title (first line of slide 1)."
},
"perSlideMaxWords": {
"type": "integer",
"description": "carousel_script / thread: words allowed per slide or post."
}
}
},
"source": {
"type": [
"string",
"null"
],
"maxLength": 200,
"description": "Where the shape came from, e.g. an import path."
},
"useFor": {
"type": [
"string",
"null"
],
"maxLength": 300,
"description": "One line: when to pick this format."
},
"example": {
"type": [
"string",
"null"
],
"maxLength": 20000
},
"archived": {
"type": "boolean"
},
"ctaSlots": {
"type": "array",
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"text": {
"type": "string"
},
"label": {
"type": "string"
},
"placement": {
"enum": [
"body",
"first_comment",
"none"
],
"type": "string",
"default": "body"
}
}
},
"maxItems": 10
},
"platform": {
"type": [
"string",
"null"
],
"description": "e.g. \"linkedin\"; null = any platform."
},
"sections": {
"type": "array",
"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
},
"maxLines": {
"type": "integer"
},
"minLines": {
"type": "integer"
},
"required": {
"type": "boolean",
"default": true
}
}
},
"maxItems": 20,
"description": "In order. \"Start from a format\" writes one `[you fill: Label — guidance]` placeholder per section."
},
"guardrails": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"maxItems": 30
},
"maxHashtags": {
"type": [
"integer",
"null"
],
"maximum": 30,
"minimum": 0
},
"hookPatterns": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300
},
"maxItems": 20,
"description": "\"[slot]\" placeholders are kept as written."
},
"defaultLabels": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 30,
"description": "\"key:value\" labels every draft started from this format gets (plus the format's own `label`)."
}
},
"additionalProperties": false
}