Flomixy

Create a DRAFT post on a Flomixy Instagram, Threads, Facebook, LinkedIn, TikTok, Pinterest, YouTube, Bluesky, or Google Business Profile account. For YOUTUBE (a video; optional yt* options such as ytTitle, ytMadeForKids, ytPrivacyStatus): a draft may omit ytTitle/ytMadeForKids, but both are required before it can be scheduled. Address the target with channel + accountId (or the legacy instagramAccountId for Instagram only). The post is always subject to approval before it can be scheduled or published — it never goes live directly, no matter what this tool is called with. If the user wants a post with an image/video but gave no URL or media id, ask first which they prefer: (a) a public link, (a2) a file the AI itself produced: upload_media with contentBase64 (one file per call, up to 10 MB, no manual step), (b) upload via a Flomixy upload link (create_upload_link; with shell access curl the returned uploadEndpoint, no base64), (c) pick from the media library (list_media), (d) a stock photo (search_stock_photos, images only), (e) generate with AI: generate_image (images only, monthly quota), (f) no media, only if the network allows it (see get_channel_capabilities). If media is already provided, do not ask.

Create a post on any Flomixy channel (Instagram, Threads, Facebook, LinkedIn, TikTok, Telegram, Pinterest, YouTube, WordPress, Bluesky, Google Business Profile; a pin always needs media, accountId is the board, and optional pinTitle/pinLink/pinAltText set the pin title, destination link and alt text; THREADS accepts an optional topicTag, the topic tag (community) the post is published under, so it reaches the community feed beyond followers) via channel + accountId, or on several networks at once via targets (each with optional caption/media/scheduledAt/firstComment overrides), for YouTube see below; optionally proposing a publish time with scheduledAt (ISO 8601 with time zone). An optional firstComment (+ firstCommentDelayMinutes) is posted as the first comment after publish, per target or post-wide (Links in Instagram and Facebook comments are NOT clickable: on FACEBOOK put the link (e.g. the blog URL) in the caption itself, on its own last line, and do not use firstComment for a link; on INSTAGRAM use "link in bio". Threads comments keep clickable links.). By default the post needs human approval and never goes live directly; optional `approval` can route it to a specific reviewer (see list_approvers) or, only for a key the owner granted POSTS_AUTO_APPROVE, skip review. Optional recyclingEnabled (+ recyclingIntervalDays/MaxRepeats/ExpiresAt) sets up Evergreen recycling for once the post is PUBLISHED; requires the POSTS_RECYCLE scope. YOUTUBE posts a video (accountId is the channel; a video is required, text-only and image posts are rejected; the caption is the video description). ytTitle and ytMadeForKids are REQUIRED on a YOUTUBE target; optional ytPrivacyStatus, ytSyntheticMedia, ytCategoryId, ytTags, ytNotifySubscribers, ytThumbnailUrl. postType "reel" publishes a Short (max length in get_channel_capabilities maxShortSeconds). YouTube has no first comment: firstComment on a YOUTUBE target fails with UNSUPPORTED_ON_CHANNEL. When the youtube flag is off the call fails with an error, it never publishes silently. Uploads are capped by YouTube's daily API quota; an over-quota publish waits for the reset instead of failing. BLUESKY posts text-first (accountId is the Bluesky account; no media is required): the caption is limited to 300 GRAPHEMES (what the user sees, maxCaptionGraphemes in get_channel_capabilities), longer text fails with a validation error before anything is saved. Up to 4 images (bskyAltTexts = alt text per image in order) OR one video, never both; links, @mentions and #hashtags in the text become clickable on their own and bskyLinkPreview adds a link card. Optional bskyReplyGate, bskyDisableQuotes, bskyContentLabels. firstComment IS supported on BLUESKY (posted as a reply to the post, links are clickable). Analytics have no impressions/reach. When the bluesky flag is off the call fails with an error, it never publishes silently. GBP posts to a Google Business Profile location (accountId is the location; the post text is the caption, limited to 1500 Unicode CODE POINTS = maxCaptionChars in get_channel_capabilities; at most ONE image, no video, text-only is fine). gbpPostKind is UPDATE (default), EVENT or OFFER: EVENT and OFFER REQUIRE gbpEventTitle, gbpEventStart and gbpEventEnd (a missing one fails with a typed GBP_EVENT_FIELDS_REQUIRED error before anything is saved); an OFFER may add gbpOfferCoupon, gbpOfferUrl, gbpOfferTerms. gbpCtaType (BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP need gbpCtaUrl; CALL takes no URL). GBP has no first comment (firstComment fails with UNSUPPORTED_ON_CHANNEL). Analytics are per location (get_account_analytics: available=false with a reason when the location is unreachable) and get_best_times is not available for GBP. When the gbp feature is off the call fails with an error, it never publishes silently. WORDPRESS publishes a blog article to a connected site (accountId is the site; postType is always ARTICLE; no media is required). title and one of contentHtml / contentMarkdown are REQUIRED on a WORDPRESS target; optional excerpt, slug, categories, tags, wpStatus (publish/draft/pending), featuredImage, featuredImageAlt. Look up real category and tag ids with list_wordpress_categories; never invent them. The article body is NOT the caption. WordPress has no first comment (UNSUPPORTED_ON_CHANNEL) and no account analytics; article metrics come from the Google Analytics of the site only when it is linked (get_post_metrics). When the wordpress feature is off the call fails with an error, it never publishes silently. A post created without scheduledAt and without publishNow stays a draft: it is NOT scheduled and will never publish by itself. If the user did not say when to publish, ask them for a time before creating the post. For "publish now" use publishNow:true together with approval:{mode:"none"}, but only if the API key allows it (POSTS_AUTO_APPROVE); otherwise propose a scheduledAt and tell the user a human must approve. If the user wants a post with an image/video but gave no URL or media id, ask first which they prefer: (a) a public link, (a2) a file the AI itself produced: upload_media with contentBase64 (one file per call, up to 10 MB, no manual step), (b) upload via a Flomixy upload link (create_upload_link; with shell access curl the returned uploadEndpoint, no base64), (c) pick from the media library (list_media), (d) a stock photo (search_stock_photos, images only), (e) generate with AI: generate_image (images only, monthly quota), (f) no media, only if the network allows it (see get_channel_capabilities). If media is already provided, do not ask.

Create a single-use Flomixy link (valid about 10 minutes) where the user uploads one image or video from their device. Give the link to the user and tell them it expires at `expiresAt`. After they upload, call list_media to get the new file url and pass it in `mediaUrls`. Clients with shell access can skip the user: POST the file as multipart field `file` to `uploadEndpoint` (the `curl` example; answers {id,url,mediaType}), no base64 and no 10 MB inline limit. The link is single-use: one link per file, so 8 slides need 8 calls. Needs the MEDIA_WRITE scope.

Create a category on a connected WordPress site and return {id, name, slug, created}; created=false means a category with that name already existed (no duplicate is made). Use the id in create_post categories. 403 means the WordPress user connected to Flomixy may not create categories (WORDPRESS_TERM_CREATE_FORBIDDEN). Only create what the user asked for: check list_wordpress_categories first. Requires scope ACCOUNTS_WRITE (a key issued before that scope existed must be re-issued).

Create a tag on a connected WordPress site and return {id, name, slug, created}; created=false means a tag with that name already existed (no duplicate is made). Use the id in create_post tags. 403 means the WordPress user connected to Flomixy may not create tags (WORDPRESS_TERM_CREATE_FORBIDDEN). Requires scope ACCOUNTS_WRITE (a key issued before that scope existed must be re-issued).

Delete a post that is still a draft, whether it was created in the Flomixy app or through the API. Scheduled, paused, publishing and failed posts cannot be deleted (409), and neither can published ones unless the environment is a dev/staging one that allows it; in that case the published post is also removed from each network and the result lists the outcome per network. Requires scope POSTS_DELETE, which is only offered to members allowed to delete posts. Check the post with get_post first: posts with the same caption on different networks are separate drafts, not duplicates.

Delete a draft, scheduled or paused post that was created through the API, cancelling its pending publish. Refused with 409 when the post was created in the Flomixy app, or when any network target is already published or publishing. It never deletes anything on a social network. Use delete_draft for app-created drafts. Requires scope POSTS_WRITE.

Generate an image from a text prompt (1-1000 chars) and save it to the media library. aspect: 1:1 (default), 4:5, 9:16, 16:9 or 1.91:1. Returns id, url and mediaType; pass the url in mediaUrls of create_post / create_draft_post. Requires the MEDIA_WRITE scope. Limited by a monthly quota: HTTP 429 means it is spent, do not retry right away. 502 is a provider failure and can be retried; 503 with code FEATURE_DISABLED means AI images are not enabled on this deployment, never retry and use another media option; 422 means the prompt was rejected or storage quota is full.

Runs the same RSS → social posts flow as the Flomixy app for an article already in a connected feed: one AI-written caption per target network (with the article link and the feed image, same as the app's "AI variants"). Never publishes directly: without scheduledAt the posts stay DRAFTS; with scheduledAt they are scheduled but still wait for human approval. Pick times with get_best_times / get_next_free_slot. Must be at least 10 minutes from now, otherwise SCHEDULED_TOO_SOON (not retryable; the error names the earliest allowed time). Get feedId/itemId from list_rss_feeds and accountId from list_accounts. Each network uses one AI caption unit; networks that cannot be generated (duplicate caption, account not owned by the feed's brand, or the article is already posted/scheduled/drafted on that very account: reason ALREADY_POSTED with `existingPostId` and `existingStatus`) come back in `skipped`, not as an error; no AI unit is spent for them. Use `force` only if the user wants another post anyway. Requires scope POSTS_WRITE.

Get analytics metrics for a connected social account. Empty/available=false is not an error (see reason: NOT_SUPPORTED for networks without analytics such as WordPress and LinkedIn; e.g. NOT_AVAILABLE or PROVIDER_ERROR when a YouTube channel has not granted the Analytics API or YouTube rejected the call); the window must end today (or yesterday), max 90 days, and is served as the trailing 7/30/90 days (the response `range` shows the window actually used); for a BLUESKY account the response carries `impressions` and `reach` as {available:false, reason: NOT_PROVIDED_BY_NETWORK} because Bluesky does not expose them (never treat that as zero or as an error); a GBP account is a location and its analytics are per location: a location the connection can no longer access returns available=false with a reason (NOT_AVAILABLE or PROVIDER_ERROR), never an error; requires scope ANALYTICS_READ (the key can only be created by the workspace owner).

Read-only. Approval state of one post: required, approvedAt, approverName and changeRequestNote (the approver's requested changes, so you can fix the draft). The agent cannot decide approval; a human does.

Best times to post for one account on any network (YouTube included), ranked from its own history. Returns suggestions plus `basis` (METRICS = engagement numbers, PUBLISH_HISTORY = frequency only); an account with no posts returns an empty list with reason NO_HISTORY. GOOGLE BUSINESS PROFILE has no engagement data to rank by: it returns empty suggestions with reason NOT_SUPPORTED (not an error). Requires the SCHEDULE_READ scope (key issued by the workspace owner).

Post limits of one network before creating a post: maxCaptionBytes (UTF-8 bytes), minMedia, maxMedia, allowsText, postTypes and feature flags. Link rules: linkInCaption / linkInComment are 'clickable' (URL is tappable), 'plain' (shown as text, not tappable) or 'unsupported' (the place does not exist, e.g. LinkedIn/Telegram/TikTok/Pinterest/YouTube/GBP reject firstComment with HTTP 400); linkInBioOnly=true (Instagram, TikTok) means no URL is clickable anywhere, so write 'link in bio' instead of a URL. Put links only where clickable. PINTEREST items also carry accessTier: 'trial' means pins are visible only to their creator until Pinterest approves Standard access (scheduling still works, tell the user); 'standard' means public; absent = unknown. PINTEREST items also carry maxPinTitleChars (100) and maxPinAltTextChars (500) for create_post pinTitle/pinAltText. THREADS items carry topicTag (true: create_post/update_post accept a topicTag) and maxTopicTagChars (50). YOUTUBE items carry maxYtTitleChars (100), maxYtTagsChars (500) and maxShortSeconds (postType reel = Short), and when core-api reports it dailyQuotaRemaining (uploads left today, 0 = the publish is deferred) with quotaResetsAt (ISO time of the next reset, 00:00 America/Los_Angeles); YouTube has no first comment (UNSUPPORTED_ON_CHANNEL) and needs a video. BLUESKY items carry maxCaptionGraphemes (300, counted in graphemes = what the user sees, on top of maxCaptionBytes), maxBskyAltTextChars (2000), maxMedia 4 (images, or one video), allowsText true; Bluesky supports firstComment (a reply, links clickable) and has no impressions/reach analytics. WORDPRESS items describe a blog article (postTypes [ARTICLE]): wpRequiredFields (wpTitle, wpContentHtml; create_post takes title and contentHtml/contentMarkdown), maxWpTitleChars, maxWpExcerptChars, maxWpContentBytes, maxWpTermIds, wpAllowedImageMimes for featuredImage, and a note: article metrics only via a linked Google Analytics, no account analytics and no first comment. GBP (Google Business Profile) items carry maxCaptionChars (1500, counted in Unicode code points on top of maxCaptionBytes), maxMedia 1 (one image, no video, text-only allowed), gbpPostKinds (UPDATE, EVENT, OFFER) and gbpCtaTypes; EVENT and OFFER need gbpEventTitle/gbpEventStart/gbpEventEnd, and GBP has no first comment (UNSUPPORTED_ON_CHANNEL), no best times and only location-level analytics. Read live from core-api. Requires scope ACCOUNTS_READ.

Next free queue slot of one account on any network, as `{scheduledAt}` (ISO time, null when no schedule is configured or every slot is booked). Pass it as scheduledAt of create_post. Requires the SCHEDULE_READ scope (key issued by the workspace owner).

Get one post by id: status (a scheduled post that was paused with pause_post reads paused; scheduledAt is kept), needsReschedule (true when the post was approved after its scheduled time, or is still unapproved past it: it will not auto-publish until the user picks a new time in the app; also per target), scheduledAt, publishedAt, permalink, platformPostId (null until published), approvalRequired and approval {required, approvedAt, approverName, changeRequestNote} (same shape as get_approval_status), Evergreen recycling settings (recyclingEnabled, recyclingIntervalDays, recyclingMaxRepeats, recyclingExpiresAt) and, per target (network), its channel, accountId, status, needsReschedule, platformPostId, permalink (link to the post on that network, null until published) publishedAt and deletedOnNetworkAt (ISO time the post was found deleted directly on that network, null otherwise; when set the permalink no longer works), plus its first comment (text, delayMinutes, status, permalink). A WORDPRESS target also carries a `wordpress` block: title, slug, excerpt, wpStatus, categoryIds, tagIds, featuredImage {url, alt} and the article body contentHtml, so an article can be read back before update_post. The post-level permalink is the Instagram one; use targets[].permalink for Threads and other networks.

Read-only. Comments left during approval of one post (change requests and approval notes), oldest first, so you can see what the reviewer asked for. Not the scheduled first comment. The agent cannot write or reply to review comments.

Get metrics of a published post. Empty/available=false is not an error (see reason, e.g. NOT_PUBLISHED). A WORDPRESS article has views, users and avgEngagementSec only when its site is linked to Google Analytics (nightly snapshot, up to 48 h behind); otherwise reason GA4_NOT_CONNECTED or GA4_NO_ACCESS (never treat as zero). Requires scope ANALYTICS_READ (the key can only be created by the workspace owner).

List the connected social accounts of the API key's workspace across all networks, YouTube channels, Bluesky accounts and Google Business Profile locations included (use the account id as accountId in create_post). Optional channel filter; `unavailableChannels` names networks whose accounts could not be loaded. Requires scope ACCOUNTS_READ.

List the workspace members who can approve posts (id, name). Pass an id as create_post's approval.approverId to send a post to that person for review. Requires scope POSTS_WRITE. You cannot approve or reject posts yourself.

List the brands of the API key's workspace with the accounts (id, channel) attached to each and whether the owner requires approval. Requires scope ACCOUNTS_READ.

List the saved hashtag sets of the API key's workspace (id, name, hashtags).

List the media library of the API key's workspace, newest first (id, url, mediaType).

Read-only. Posts still waiting for a human decision (id, status, scheduledAt, approval). The agent cannot decide approval.

List posts of the API key's workspace (JSON with items, total, limit, offset; each item carries targets[] with channel, accountId and status, and needsReschedule on the post and each target, so the same caption on several networks is one post per network, not a duplicate; a WORDPRESS target carries its article summary but not the body: use get_post for contentHtml), optionally filtered by status (draft, scheduled, paused, publishing, published, failed, missed_slot: scheduled posts approved after their time, or still unapproved past it, that will not auto-publish until the user picks a new time; plain scheduled excludes them), channel, brandId and a scheduledAt range (from/to).

List the RSS / blog feeds connected in Flomixy, each with its newest items (id, title, link, status new/drafted/ignored, postStatus). Use a feed id + item id (or the item link) with generate_posts_from_rss_item to turn a blog article into social posts. Requires scope ACCOUNTS_READ.

List the categories (id, name, parent, depth, path such as "Food > Recipes") of a connected WordPress site and, when `search` is given, the tags matching it. Use the ids or exact names in create_post categories / tags; never invent them. Categories are cached for a few minutes on the server. Requires scope ACCOUNTS_READ.

Pause a scheduled post: status becomes paused, scheduledAt is kept and nothing is published until resume_post. Only scheduled posts can be paused (publishing/published: 409 POST_NOT_PAUSABLE, not retryable). Requires a key with write scope.

Move a scheduled post (any network) to a new publish time, on every network target that is not yet published. Only posts with status scheduled can be moved: a paused post answers 409 POST_NOT_RESCHEDULABLE (use resume_post with scheduledAt instead), a draft or published one too. The time must respect the minimum lead (400 SCHEDULED_TOO_SOON). Approval is NOT changed or bypassed: an approved post stays approved, an unapproved one still needs a human. Requires scope POSTS_WRITE.

Resume a paused post. Without arguments it keeps the original time; if that time has passed core-api answers 409 SCHEDULED_AT_IN_PAST with a suggested slot, so ask the user for a new time (scheduledAt), or use mode "next_slot". mode "now" publishes immediately and is rejected with 403 unless the key has the POSTS_AUTO_APPROVE scope. Requires a key with write scope.

Search free stock photos (Pexels + Pixabay) by keyword. Returns url, thumbnailUrl and author; pass a url in mediaUrls of create_post / create_draft_post when the user has no media of their own. Requires the MEDIA_READ scope.

Edit the caption and/or media of a DRAFT (created in the Flomixy app or through the API) or of a post created through the API that is not yet published, and/or set or change the first comment (and its delay) and, on THREADS targets, the topicTag (null removes it) of individual existing targets via targets. Scheduled or published posts created in the app are refused (403), published posts cannot be edited (409) and a published first comment is locked. Needs the POSTS_WRITE scope and a member allowed to edit posts (posts:edit). On a WORDPRESS target the article fields (title, contentHtml/contentMarkdown, excerpt, slug, categories, tags, wpStatus, featuredImage, featuredImageAlt) can be edited the same way, only the ones you send change; once the article is published, any such edit is refused (409). Approval and the set of targets cannot be changed. Optional recyclingEnabled (+ recyclingIntervalDays/MaxRepeats/ExpiresAt) toggles Evergreen recycling and, unlike caption/media, works on an already-published post; requires the POSTS_RECYCLE scope.

Add an image or video to the API key's workspace media library. Returns id and url — pass the url in `mediaUrls` of create_post. Two modes, exactly one per call: `url` (direct http(s) link to the file; up to 3 redirects followed; Google Drive "anyone with the link" file links are converted automatically, other share pages such as Dropbox/WeTransfer and large Drive files with a virus-scan page are NOT supported — use create_upload_link or contentBase64 for those) or `contentBase64` + `mimeType` (+ `filename`) for a file you generated yourself — one file per call (call it once per slide, e.g. 8 calls for an 8-slide carousel), JPEG/PNG/WebP/GIF/MP4/MOV, up to 10 MB decoded; prefer small/compressed files since base64 costs output tokens and hand-copied base64 of large files is error-prone: with shell access use create_upload_link + curl instead. Truncated or checksum-mismatched base64 is rejected with a clear error. Files above the size limit, wrong or mismatched types, private/localhost URLs and a full storage quota are rejected with a clear error. Needs the MEDIA_WRITE scope. If the user wants a post with an image/video but gave no URL or media id, ask first which they prefer: (a) a public link, (a2) a file the AI itself produced: upload_media with contentBase64 (one file per call, up to 10 MB, no manual step), (b) upload via a Flomixy upload link (create_upload_link; with shell access curl the returned uploadEndpoint, no base64), (c) pick from the media library (list_media), (d) a stock photo (search_stock_photos, images only), (e) generate with AI: generate_image (images only, monthly quota), (f) no media, only if the network allows it (see get_channel_capabilities). If media is already provided, do not ask.