# Flung documentation

> Connect the social accounts of the people using your app, then schedule and publish posts to X, LinkedIn, Instagram, Bluesky and more over REST, from TypeScript, or through MCP.

Every page below is a Markdown file. The address of any page on this site, with `.md` added, returns that page as Markdown with its links already pointing at other Markdown pages, so an agent can follow them without a browser. Sizes are rough token counts. To read a whole subject, fetch the bundle of its tab (`llms-<tab>.txt`, listed under Machine-readable files) rather than the whole documentation. Pages marked optional are catalogues and policies: read them only when the task needs them.

## Guides: Get started

- [Quick start](https://docs.flung.dev/quick-start.md): Connect a social account and publish your first post through Flung, from your server or from an AI agent. (1.4k tokens)
- [Authentication](https://docs.flung.dev/authentication.md): Every call to the Flung API carries one credential in the Authorization header. There are three kinds, for three places a call can come from. (908 tokens)
- [Connect an AI agent](https://docs.flung.dev/mcp.md): Give an AI agent Flung's tools through its MCP server, so it can connect accounts, schedule posts, retry failures and answer comments for you. (434 tokens)

## Guides: Build

- [Add account connecting to your site](https://docs.flung.dev/connect-accounts.md): Put a panel on your own page where your users connect, reconnect and disconnect their social accounts, without your API key ever reaching the browser. (3.2k tokens)
- [Publish and schedule posts](https://docs.flung.dev/posting.md): Post to one account or many at once, now or at a set time, and see what happened on each. (975 tokens)
- [Images and video](https://docs.flung.dev/media.md): Attach images or a video to a post: upload the file, or let Flung fetch it from a link, then pass its id in mediaIds. (578 tokens)
- [Webhooks](https://docs.flung.dev/webhooks.md): Have Flung tell your server when posts publish or fail and when accounts need a person, instead of asking again and again. (717 tokens)
- [Retries, limits and errors](https://docs.flung.dev/reliability.md): How Flung keeps a retry from posting twice, how fast you may call it, and what a failure tells you. (365 tokens)

## Reference: Overview

- [API reference](https://docs.flung.dev/reference/api.md): Every endpoint of the Flung REST API, grouped by what it does, with a page each that has its parameters, its answers and code samples in curl, TypeScript and fetch. (2.7k tokens)
- [TypeScript SDK](https://docs.flung.dev/reference/sdk.md): @flung.dev/sdk is the typed client for the Flung API: every endpoint as a method, with retries, idempotency keys and typed errors. It runs anywhere with fetch and Web Crypto: Node 20 or newer, Cloudflare Workers, Deno and Bun. (4.1k tokens)
- [Connect panel](https://docs.flung.dev/reference/connect.md): @flung.dev/connect gives your page <flung-connect>, a panel where people connect, reconnect and disconnect their social accounts, and <FlungConnect> for React. It takes a connect token your server makes, never an API key. (1.8k tokens)
- [MCP tools](https://docs.flung.dev/reference/mcp.md): The 28 tools Flung's MCP server gives an AI agent: connect and reconnect social accounts, schedule and retry posts, read and answer comments, and automate posting. (1.3k tokens)
- [Errors](https://docs.flung.dev/reference/api/errors.md): Every failed call answers with the same JSON shape and a stable code. Branch on the code; the message is for people and may change. (746 tokens)

## For AI agents: AI agents

- [Flung for AI agents](https://docs.flung.dev/agents/overview.md): What an AI agent needs to use Flung, and to build Flung into someone's product: which way in to choose, the order of calls, and the rules that keep posts and accounts safe. (907 tokens)
- [Add Flung to a website](https://docs.flung.dev/agents/build.md): A recipe for a coding agent: add account connecting and posting to a web app with Flung. Follow the steps in order; each file below is from a working example app and can be copied as it is. (1.9k tokens)
- [Rules file for your agent](https://docs.flung.dev/agents/rules.md): A block to paste into CLAUDE.md, AGENTS.md or an editor's rules file, so an agent uses Flung the right way. It is the guidance the MCP server sends when a client connects. (623 tokens)
- [Prompts and recipes](https://docs.flung.dev/agents/prompts.md): Things to ask an agent connected to Flung, and the tools it calls for each. Every prompt below is one the tools are tested against. (1.3k tokens)
- [Files for agents](https://docs.flung.dev/agents/machine-readable.md): Every file this site serves for programs and AI agents, and when to fetch each. (278 tokens)

## Machine-readable files

- [llms.txt](https://docs.flung.dev/llms.txt): An index of every page: its title, address, a line on what it holds, and its size in tokens. You do not know which page you need. Read this first.
- [llms-docs.txt](https://docs.flung.dev/llms-docs.txt): The text of every page in the Guides tab except the optional ones, in one file. You need all of Guides in one fetch. A tab bundle is the recommended way to load a whole subject. (8.7k tokens)
- [llms-reference.txt](https://docs.flung.dev/llms-reference.txt): The text of every page in the Reference tab except the optional ones, in one file. You need all of Reference in one fetch. A tab bundle is the recommended way to load a whole subject. (10.8k tokens)
- [llms-agents.txt](https://docs.flung.dev/llms-agents.txt): The text of every page in the For AI agents tab except the optional ones, in one file. You need all of For AI agents in one fetch. A tab bundle is the recommended way to load a whole subject. (5.1k tokens)
- [llms-full.txt](https://docs.flung.dev/llms-full.txt): The text of every page except the optional ones, in one file. It is the largest file here. You are loading the whole documentation into a search index. For a task, read a tab bundle instead. (24.3k tokens)
- [tools.json](https://docs.flung.dev/tools.json): The name, description, behavior hints, and JSON Schema of every tool of the MCP server. You build a client or a tool call and need the exact schema.
- [openapi.json](https://docs.flung.dev/openapi.json): The OpenAPI 3.1 document of the HTTP API. You call the HTTP API and want a generated client or the exact request and response shapes.
- [sitemap.xml](https://docs.flung.dev/sitemap.xml): The address of every page. You crawl the site.
- [robots.txt](https://docs.flung.dev/robots.txt): What crawlers may fetch, and where the sitemap is. You run a crawler.

## Optional

- [Schemas](https://docs.flung.dev/reference/api/schemas.md): Every named request and response type of the API, with its fields. Each endpoint page links the types it uses. (9.6k tokens)
- [List posts](https://docs.flung.dev/reference/api/get-v1-posts.md): Newest first. (1.2k tokens)
- [Schedule a post](https://docs.flung.dev/reference/api/post-v1-posts.md): Schedules one post to one or more connected accounts. (5.7k tokens)
- [Get a post](https://docs.flung.dev/reference/api/get-v1-posts-id.md): Get a post. (1.5k tokens)
- [Change a scheduled post](https://docs.flung.dev/reference/api/patch-v1-posts-id.md): Its content, media, publish time or per-platform overrides, until it starts publishing. (5.5k tokens)
- [Delete a post](https://docs.flung.dev/reference/api/delete-v1-posts-id.md): Removes it from Flung, cancelling it if scheduled. (646 tokens)
- [Cancel a scheduled post](https://docs.flung.dev/reference/api/post-v1-posts-id-cancel.md): Cancel a scheduled post. (1.5k tokens)
- [Retry the failed accounts of a post](https://docs.flung.dev/reference/api/post-v1-posts-id-retry.md): Schedules the targets that failed for now; those already published are left alone. (1.5k tokens)
- [Read a post's counts](https://docs.flung.dev/reference/api/get-v1-posts-id-metrics.md): Views, likes, comments, reposts and quotes for each account the post was published to, read from the platforms now. (1.2k tokens)
- [List connected accounts](https://docs.flung.dev/reference/api/get-v1-accounts.md): Filter with reconnectBefore to find the accounts a person must reconnect soon. (1.5k tokens)
- [Get a connected account](https://docs.flung.dev/reference/api/get-v1-accounts-id.md): Get a connected account. (1.3k tokens)
- [Change an account's settings](https://docs.flung.dev/reference/api/patch-v1-accounts-id.md): Sets the default Pinterest board, or whether comments and mentions are read into the inbox. (1.4k tokens)
- [Disconnect an account](https://docs.flung.dev/reference/api/delete-v1-accounts-id.md): Deletes the stored tokens. (1.4k tokens)
- [Refresh an account now](https://docs.flung.dev/reference/api/post-v1-accounts-id-refresh.md): Renews the access token now instead of waiting for the hourly renewal, and reports whether the platform still accepts the account. (1.6k tokens)
- [List Pinterest boards](https://docs.flung.dev/reference/api/get-v1-accounts-id-boards.md): The boards a Pinterest account can pin to, read from Pinterest now, so a person can pick the default. (797 tokens)
- [Read what a post may choose](https://docs.flung.dev/reference/api/get-v1-accounts-id-posting-options.md): TikTok only: the creator's name, the audiences they may post to, which interactions they turned off and the longest video allowed, read from TikTok now. (1.1k tokens)
- [Make a connect token for a page](https://docs.flung.dev/reference/api/post-v1-connect-tokens.md): Lets a page in a browser show "connect your accounts" without holding your API key: make the token on your server, hand it to the page, and the page (with <flung-connect> from @flung.dev/connect, or its own calls) can list, connect, reconnect and disconnect accounts until it expires, from the listed origins only. (1.3k tokens)
- [Start connecting an account](https://docs.flung.dev/reference/api/post-v1-connect-platform.md): Starts a connect session. (1.5k tokens)
- [Start reconnecting an account](https://docs.flung.dev/reference/api/post-v1-accounts-id-reconnect.md): For an account that is needs_reconnect or disconnected. (1.4k tokens)
- [Get a connect session](https://docs.flung.dev/reference/api/get-v1-connect-sessions-id.md): Poll this after sending the person to authorizationUrl until status is no longer pending. (1.2k tokens)
- [List webhook endpoints](https://docs.flung.dev/reference/api/get-v1-webhook-endpoints.md): List webhook endpoints. (777 tokens)
- [Add a webhook endpoint](https://docs.flung.dev/reference/api/post-v1-webhook-endpoints.md): Flung POSTs each subscribed event to the URL, signed to the Standard Webhooks spec with the returned secret, and retries failures with backoff for about 15 hours. (1.1k tokens)
- [Rotate a signing secret](https://docs.flung.dev/reference/api/post-v1-webhook-endpoints-id-rotate-secret.md): Issues a new secret. (883 tokens)
- [Change an endpoint](https://docs.flung.dev/reference/api/patch-v1-webhook-endpoints-id.md): Its URL, its events, or whether it is enabled. (985 tokens)
- [Delete a webhook endpoint](https://docs.flung.dev/reference/api/delete-v1-webhook-endpoints-id.md): Stops deliveries at once, including retries already waiting. (644 tokens)
- [Send a test event](https://docs.flung.dev/reference/api/post-v1-webhook-endpoints-id-ping.md): Delivers a signed webhook.ping event to the endpoint, with the usual retries; its outcome shows in the deliveries. (782 tokens)
- [List deliveries](https://docs.flung.dev/reference/api/get-v1-webhook-endpoints-id-deliveries.md): Recent deliveries to the endpoint, newest first, with their attempts and the endpoint's last answer. (1.1k tokens)
- [List API keys](https://docs.flung.dev/reference/api/get-v1-api-keys.md): List API keys. (868 tokens)
- [Create an API key](https://docs.flung.dev/reference/api/post-v1-api-keys.md): To rotate a key: create the new one, deploy it, then revoke the old one. (1.1k tokens)
- [Revoke an API key](https://docs.flung.dev/reference/api/delete-v1-api-keys-id.md): The key stops working at once. (681 tokens)
- [Who is calling](https://docs.flung.dev/reference/api/get-v1-me.md): The workspace this credential acts on, and the person behind it for an OAuth token. (749 tokens)
- [List members](https://docs.flung.dev/reference/api/get-v1-members.md): The people who may sign in and connect apps to this workspace with OAuth. (751 tokens)
- [Add a member](https://docs.flung.dev/reference/api/post-v1-members.md): Lets a person, by email, sign in to Flung and connect apps to this workspace. (981 tokens)
- [Remove a member](https://docs.flung.dev/reference/api/delete-v1-members-userid.md): Every app the person connected to this workspace stops working at once. (651 tokens)
- [List files](https://docs.flung.dev/reference/api/get-v1-media.md): Newest first. (1.1k tokens)
- [Start an upload](https://docs.flung.dev/reference/api/post-v1-media.md): Reserves a file and says how to send it: one PUT to uploadUrl up to 100 MB, or multipart parts for a larger video (give bytes). (1.4k tokens)
- [Upload one part](https://docs.flung.dev/reference/api/put-v1-media-id-parts-partnumber.md): One part of a multipart upload, as the raw body with its Content-Length. (942 tokens)
- [Finish a multipart upload](https://docs.flung.dev/reference/api/post-v1-media-id-complete.md): Finish a multipart upload. (1.1k tokens)
- [Upload the bytes](https://docs.flung.dev/reference/api/put-v1-media-id-content.md): The raw file as the body, with its Content-Length. (1.3k tokens)
- [Import a file from a URL](https://docs.flung.dev/reference/api/post-v1-media-import.md): Flung fetches a public https file and keeps its own copy, ready to post. (1.3k tokens)
- [Get a file](https://docs.flung.dev/reference/api/get-v1-media-id.md): Get a file. (1.1k tokens)
- [Delete a file](https://docs.flung.dev/reference/api/delete-v1-media-id.md): Removes the file. (631 tokens)
- [List templates](https://docs.flung.dev/reference/api/get-v1-templates.md): List templates. (1.0k tokens)
- [Create a template](https://docs.flung.dev/reference/api/post-v1-templates.md): Create a template. (5.4k tokens)
- [Get a template](https://docs.flung.dev/reference/api/get-v1-templates-id.md): Get a template. (1.4k tokens)
- [Change a template](https://docs.flung.dev/reference/api/patch-v1-templates-id.md): Change a template. (5.4k tokens)
- [Delete a template](https://docs.flung.dev/reference/api/delete-v1-templates-id.md): Delete a template. (618 tokens)
- [Schedule a post from a template](https://docs.flung.dev/reference/api/post-v1-templates-id-deploy.md): Creates a post from the template, to its accounts or the ones given, filling {{variables}}. (1.7k tokens)
- [List variables](https://docs.flung.dev/reference/api/get-v1-variables.md): {{name}} values filled into post text when a post is created. (766 tokens)
- [Set a variable](https://docs.flung.dev/reference/api/put-v1-variables-name.md): Set a variable. (869 tokens)
- [Delete a variable](https://docs.flung.dev/reference/api/delete-v1-variables-name.md): Delete a variable. (604 tokens)
- [List feeds](https://docs.flung.dev/reference/api/get-v1-feeds.md): List feeds. (864 tokens)
- [Follow an RSS or Atom feed](https://docs.flung.dev/reference/api/post-v1-feeds.md): Every new item becomes a post to the accounts, written from the template. (1.1k tokens)
- [Change a feed](https://docs.flung.dev/reference/api/patch-v1-feeds-id.md): Change a feed. (983 tokens)
- [Stop following a feed](https://docs.flung.dev/reference/api/delete-v1-feeds-id.md): Stop following a feed. (613 tokens)
- [List platforms and their limits](https://docs.flung.dev/reference/api/get-v1-platforms.md): What each platform accepts, so a post can be checked before it is sent. (1.0k tokens)
- [Suggest when to post](https://docs.flung.dev/reference/api/get-v1-posting-times.md): The next times a platform's audience is usually most active, in the audience's time zone, as instants to pass to publishAt. (981 tokens)
- [API requests per credential per day](https://docs.flung.dev/reference/api/get-v1-usage.md): Each API key and OAuth app's requests and errors per UTC day, oldest first. (812 tokens)
- [Workspace statistics](https://docs.flung.dev/reference/api/get-v1-stats.md): Posts due in a window by status, publishes per platform by status, and the accounts and stored media now. (948 tokens)
- [List comments and mentions](https://docs.flung.dev/reference/api/get-v1-inbox.md): Comments on the accounts' posts and mentions of them, newest first, read from each platform about every 15 minutes. (1.2k tokens)
- [Get an inbox item](https://docs.flung.dev/reference/api/get-v1-inbox-id.md): Get an inbox item. (1.0k tokens)
- [Mark an item read, unread or archived](https://docs.flung.dev/reference/api/patch-v1-inbox-id.md): Mark an item read, unread or archived. (1.2k tokens)
- [Reply publicly](https://docs.flung.dev/reference/api/post-v1-inbox-id-reply.md): Answers the comment or mention on the platform, as the account it was addressed to, and marks it replied. (1.3k tokens)
- [Read an account's inbox now](https://docs.flung.dev/reference/api/post-v1-accounts-id-inbox-sync.md): Reads new comments and mentions now rather than at the next 15-minute read. (773 tokens)
- [Read XP, level and achievements](https://docs.flung.dev/reference/api/get-v1-experience.md): XP for each published post and each achievement, counted from the workspace's own activity. (1.1k tokens)
- [Read the leaderboard](https://docs.flung.dev/reference/api/get-v1-leaderboard.md): Workspaces that chose to be listed, most XP first. (800 tokens)
- [Join the leaderboard](https://docs.flung.dev/reference/api/put-v1-leaderboard-entry.md): Lists the workspace under name, which every Flung customer can see. (1.2k tokens)
- [Leave the leaderboard](https://docs.flung.dev/reference/api/delete-v1-leaderboard-entry.md): Leave the leaderboard. (541 tokens)
- [find_accounts_needing_attention](https://docs.flung.dev/reference/mcp/find-accounts-needing-attention.md): Find accounts that need a person. Start here to keep accounts working. Returns every account that is already needs_reconnect or must be reconnected within withinDays (reconnectBy). (523 tokens)
- [list_accounts](https://docs.flung.dev/reference/mcp/list-accounts.md): List connected accounts. Every account in the workspace with its id, platform, username, status and renewal (automatic, manual, not_needed), tokenExpiresAt and reconnectBy. Use it for account ids before schedule_post. (524 tokens)
- [get_account](https://docs.flung.dev/reference/mcp/get-account.md): Get an account. One account with its status, renewal, tokenExpiresAt and reconnectBy. Use after a reconnect to confirm it is active again. (408 tokens)
- [connect_account](https://docs.flung.dev/reference/mcp/connect-account.md): Connect a new account. Starts connecting a new social account and returns a session with an authorizationUrl, the platform's own consent page. (604 tokens)
- [reconnect_account](https://docs.flung.dev/reference/mcp/reconnect-account.md): Reconnect an account. For an account that is needs_reconnect, disconnected, or near its reconnectBy. (551 tokens)
- [get_connect_session](https://docs.flung.dev/reference/mcp/get-connect-session.md): Check a connect session. Whether the person finished connecting: pending, connected (with accountIds), failed (with the platform's reason) or expired. (484 tokens)
- [refresh_account](https://docs.flung.dev/reference/mcp/refresh-account.md): Refresh an account now. Renews the access token now and reports refreshed, not_needed, reconnect_required or failed. (484 tokens)
- [disconnect_account](https://docs.flung.dev/reference/mcp/disconnect-account.md): Disconnect an account. Deletes the stored tokens: the account stops posting until a person reconnects it. Only when the person asks for it, and pass confirm: true. To fix a broken account, use reconnect_account instead. (497 tokens)
- [get_posting_options](https://docs.flung.dev/reference/mcp/get-posting-options.md): Read a TikTok account's posting options. TikTok: the creator's name, allowed audiences and longest video. TikTok wants the person to pick the audience (platformOverrides.tiktok.privacyLevel). (449 tokens)
- [schedule_post](https://docs.flung.dev/reference/mcp/schedule-post.md): Schedule a post. Schedules one post to one or more accounts, now or at publishAt, and returns it with a target per account. Get account ids from list_accounts first. Pass the same idempotencyKey when retrying, or the post may go out twice. (712 tokens)
- [update_post](https://docs.flung.dev/reference/mcp/update-post.md): Change a scheduled post. Changes the content, media or time of a post not yet publishing. Its accounts stay the same. (540 tokens)
- [cancel_post](https://docs.flung.dev/reference/mcp/cancel-post.md): Cancel a scheduled post. Stops a post that has not started publishing. Only when the person asks; it cannot be undone, but the post can be scheduled again. (424 tokens)
- [retry_post](https://docs.flung.dev/reference/mcp/retry-post.md): Retry a post's failed accounts. Publishes again, now, to the accounts where a post failed; those already published are left alone. Fix the cause first (reconnect_account for a reconnect error). (430 tokens)
- [import_media](https://docs.flung.dev/reference/mcp/import-media.md): Add an image or video from a URL. Flung fetches a public https image or video and keeps a copy; pass the returned id in mediaIds to schedule_post. JPEG, PNG, WebP, GIF, MP4 and QuickTime, up to 100 MB this way. (433 tokens)
- [get_post](https://docs.flung.dev/reference/mcp/get-post.md): Get a post. A post with its result on each account: published with the platform URL, or failed with the reason. Use after schedule_post to report the outcome. (410 tokens)
- [list_posts](https://docs.flung.dev/reference/mcp/list-posts.md): List posts. Posts newest first with their status. For the next page pass the last id as startingAfter while hasMore is true. (485 tokens)
- [get_post_metrics](https://docs.flung.dev/reference/mcp/get-post-metrics.md): Read a post's views and likes. Views, likes, comments and reposts per account a post went to, read from the platforms now, with totals. (404 tokens)
- [list_platforms](https://docs.flung.dev/reference/mcp/list-platforms.md): List platforms and their limits. Each platform's text limit, image count, video, whether media is required, and whether it can be connected. (346 tokens)
- [suggest_posting_times](https://docs.flung.dev/reference/mcp/suggest-posting-times.md): Suggest when to post. The next times a platform's audience is usually most active, ready for publishAt. General guidance. (471 tokens)
- [list_inbox](https://docs.flung.dev/reference/mcp/list-inbox.md): List comments and mentions. Comments on the accounts' posts and mentions of them, newest first. Pass status unread for what needs an answer. (479 tokens)
- [reply_to_inbox_item](https://docs.flung.dev/reference/mcp/reply-to-inbox-item.md): Reply to a comment or mention. Replies publicly on the platform as the account. Show the person the text first. (406 tokens)
- [list_templates](https://docs.flung.dev/reference/mcp/list-templates.md): List post templates. Reusable posts; schedule one with deploy_template. (306 tokens)
- [deploy_template](https://docs.flung.dev/reference/mcp/deploy-template.md): Schedule a post from a template. Schedules a post from a template, filling {{variables}}. (513 tokens)
- [list_variables](https://docs.flung.dev/reference/mcp/list-variables.md): List workspace variables. The {{name}} values filled into new posts. (302 tokens)
- [set_variable](https://docs.flung.dev/reference/mcp/set-variable.md): Set a workspace variable. Sets the value of a {{name}} placeholder for new posts. (379 tokens)
- [list_feeds](https://docs.flung.dev/reference/mcp/list-feeds.md): List RSS feeds. RSS feeds that post their new items, with their last error. (303 tokens)
- [follow_feed](https://docs.flung.dev/reference/mcp/follow-feed.md): Post new items from an RSS feed. Posts each new item of an RSS or Atom feed to the accounts, from template ({{title}}, {{link}}, {{summary}}). Existing items are skipped. (439 tokens)
- [get_experience](https://docs.flung.dev/reference/mcp/get-experience.md): Read XP, level and achievements. The workspace's XP, level, posting streak and each achievement with its progress. (335 tokens)