Who may call these
Every paid Fly plan: the API works on a business on a paid plan, or with access from Fly. Fly AI has credits of its own. Under a key held to some agents, get and events answer only those agents' cards and lines, and event_detail, runs, action_status, growth_state and notifications, which answer every agent's work together, answer 403 agent_not_granted: the tools fly_home and fly_activity show the agents the key has.
New to the API? Start with Getting started: the key, the address, the errors and the limits.
Before the first call
These are done in the Fly app, signed in, because the API cannot do them.
- Make a key on the AI assistants page. A key may be held to some workspaces, locations and agents, and to reads only. In the app: AI assistants.
- Plans, payment and Fly AI credits are bought in the app.
ai_topup_linkanswers the Billing page address and buys nothing. In the app: Billing.
The working loop
- Find the location:
GET /v1/workspaceslists each workspace with its locations and theirlocation_id. - Read the home:
POST /v1/tools/fly_homewithlocation_idanswers every agent's cards that need the owner, the ones in flight, recent activity, rank and health; the opgetanswers the whole home. - Decide each card:
respondwith the card'sidasaction_idand adecision. - Read what was done:
work_summarycounts what the agent did,runslists its passes andeventsthe activity trail; each agent's report is under Reports.
curl -X POST https://www.fly-social.com/api/v1/tools/fly_home \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{"location_id":"3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84"}'Workspaces and locations
GET /v1/me answers who the key belongs to, its scopes and what it may reach. GET /v1/workspaces lists the workspaces and locations it may reach: each workspace with its workspace_id, name and eligible, each location with its location_id, name, city and agents_on.
curl -H "Authorization: Bearer fmk_your_key" https://www.fly-social.com/api/v1/mecurl -H "Authorization: Bearer fmk_your_key" https://www.fly-social.com/api/v1/workspacesThe home and its cards
A card is something the agent wants the owner to decide or do: approve a change, give an input, or note an FYI. get reads the home with its cards; respond answers one. A finished card can be checked against Google again.
| Operation | Kind | What it does | Params |
|---|---|---|---|
get | Read | The agent home: the location, the cards, the activity, rank, health, the plan. | {} |
respond | Write | Approve, decline, mark done, dismiss, submit or undo a card. | { action_id, decision: approve | reject | done | dismiss | submit | change | undo_dismiss, reply_text?, inputs? } |
fyi_seen | Write | Got it on an FYI card. | { action_id } |
card_recheck | Write | Check a finished card against Google again. | { action_id } |
card_recheck_status | Read | How a recheck is going. | { action_id } |
action_status | Read | How the cards this caller raised ended. | {} |
changed_at | Read | When the cards, drafts and reviews last changed. | {} |
health | Read | The health signals and the worker heartbeat only. | {} |
growth_state | Read | The growth loop: what moved and what is lined up. | {} |
paused_line | Read | The line held work shows while the agent is paused. | {} |
Example: Approve a card
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/respond \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: approve-9b1d2c3e-1" \
-d '{"action_id":"9b1d2c3e-4f5a-4b6c-8d7e-0f1a2b3c4d5e","decision":"approve"}'The answer. success and the card's new status. A card already closed answers already with a message and changes nothing.
Activity and passes
The agent works in passes. runs lists them, newest first, with what each did; events is the activity trail a page at a time; tick queues a pass now, all stages or the named ones (the early access gate may refuse it).
| Operation | Kind | What it does | Params |
|---|---|---|---|
events | Read | The activity trail, a page at a time. | { offset?, limit? } |
event_detail | Read | One activity line in full. | { event_id } |
runs | Read | The agent passes, newest first. | { limit?, before? } |
tick | Write | Queue a pass now, all stages or the named ones (the early access gate may refuse). | { checks?: string[] } |
work_summary | Read | Counts of what the agent did, all time and the last 30 days. | { all?: boolean } |
get_dashboard_data | Read | The dashboard numbers for the location. | {} |
Example: The activity trail
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/events \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{"limit":20}'The answer. The activity trail, newest first, a page at a time.
Telling the agent things
A standing rule, a one-off job or a question in plain words, a picture or a file with an instruction, and the standing instructions for one kind of content. To retire a rule, list the rules first and pass its id.
| Operation | Kind | What it does | Params |
|---|---|---|---|
instructions | Write | Tell the agent something (a standing rule, a one-off job, a question), retire a standing rule by its id, or list the standing rules with their ids (no params). | {} (lists the standing rules) | { instruction } | { deactivate_id } |
attach | Write | Send the agent a picture or a file with an instruction. | { media_kind, instruction, url? } |
content_instructions | Write | The standing instructions for one kind of content: list them, add one, withdraw one. | { kind: frames | posts } | { kind, add: text } | { kind, remove_id } |
instruction_generalise | Write | Turn a refine instruction into a general rule (AI; saves nothing, answers the rule to offer). | { instruction, source: post_refine | frame_refine } |
instruction_remember | Write | Keep a refine instruction as a standing rule. | { instruction, source: post_refine | frame_refine } |
Example: The standing rules
curl -X POST https://www.fly-social.com/api/v1/tools/fly_instruct \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{"location_id":"3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84","list":true}'The answer. The standing rules with their ids, the ids retire_id takes.
Settings
settings reads the agent's settings with no changes, or changes them: the mode (autonomy: approve_required, auto_safe or full_auto), the switches in enabled_checks (social_agent, ads_agent, web_agent, citations_agent among them), where alerts go and the posting days.
| Operation | Kind | What it does | Params |
|---|---|---|---|
settings | Write | Read the agent settings (no changes) or change them: mode, switches, contacts, posting days. | { changes?: { autonomy?: approve_required | auto_safe | full_auto, enabled?: boolean, enabled_checks?: { <switch>: boolean }, notify_emails?: string[], notify_phones?: string[], content_post_days?: "1,3,5" | null, auto_schedule_posts?: boolean, ... } } |
services_only | Write | Posts only about listed services: read it ({}), switch it, or set the services it may post about (null goes back to the Google list). | {} | { services_only?: boolean, approved_services?: string[] | null } |
early_access | Read | Which beta agents and staff views this account may see. | {} |
setup_dismiss | Write | Dismiss the set-up strip. | {} |
Example: Read the settings
curl -X POST https://www.fly-social.com/api/v1/tools/fly_settings \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{"location_id":"3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84"}'The answer. The agent's settings at the location: the mode, the switches, where alerts go and the posting days.
Notifications
The notifications list, and marking them read.
| Operation | Kind | What it does | Params |
|---|---|---|---|
notifications | Read | The notifications list. | { filter?, offset?, limit? } |
notification_read | Write | Mark one notification read. | { id } | { all: true } |
notification_read_all | Write | Mark every notification read. | {} |
Example: The notifications
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/notifications \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{"limit":20}'The answer. The notifications list, a page at a time.
Ask the agent
ask puts a question about the location to the agent: it answers from what it knows and never acts. The Ask panel's conversations, a refresh of a stale answer and the suggested asks are here too.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ask | Read | Ask the agent a question about this location (read only, never acts). | { question } |
ask_send | Write | A line to the agent from the Ask panel: answered from what it knows, or made into work. | { instruction, conversation_id?, new_conversation? } |
ask_conversations | Read | The Ask conversations. | {} |
ask_conversation | Write | One conversation (a pending refresh in it is claimed, so it needs fly:write). | { conversation_id } |
ask_refresh | Write | Refresh a stale answer (may queue a pass). | { conversation_id, event_id } |
ask_refresh_answer | Write | The refreshed answer (written to the conversation, so it needs fly:write). | { conversation_id, event_id } |
ask_suggestions | Read | Suggested asks. | {} |
Example: Ask a question
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ask \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{"question":"How many new reviews came in this week?"}'The answer. The agent's answer, from what it knows. It never acts.
Links
Every page of the location at its app address, a share link that opens one page without signing in, the connect links to hand to whoever manages the accounts, and a report's share links.
| Operation | Kind | What it does | Params |
|---|---|---|---|
page_links | Read | The address of every page of the location for the signed-in owner. | {} |
page_link | Write | A share link (a token page that opens without signing in) of one type. | { link_type: home | review_generator | review_responder | references | templates | social_connect } |
connect_share_links | Write | The social, ads and web connect links to share with whoever manages the accounts. | { kinds?: [social | ads | web], audience?: owner | manager, sent?: boolean } |
connect_link | Write | A fresh Google connect link for adding a location to this workspace. | {} |
report_share | Write | An agent report's share links: list, make (private or showcase), switch off. | { agent: local | social | ads | web, action: list | make | off, kind?: private | showcase, show_name?, show_money?, link_token? } |
Example: Every page of the location
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/page_links \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. The address of every page of the location for the signed-in owner.
Reports
Each agent's work report for a range of dates, Google performance by day, and the reports kept for the location. The tool fly_report answers a shorter report; these answer it whole.
| Operation | Kind | What it does | Params |
|---|---|---|---|
local_report | Read | The Local Agent's work report for a range. | { from?: YYYY-MM-DD, to?: YYYY-MM-DD } |
social_report | Read | The Social Agent's work report for a range. | { from?, to? } |
ads_report | Read | The Ads Agent's work report for a range; its part "proof" (ADS-PROOF-1) is the cost of a result of the owner's goal on the accounts Fly runs against the owner's own ads in the 30 days before Fly's first campaign, per network (not counted, or judged on clicks where the owner chose to run without counting), with the verdict; its part "status" (ADS-STATUS-1, a range to today) is where things stand: the owner's next step and what it unlocks, how many more wait, when Fly's next pass is and what it does there, one line on Fly's own work kept within its allowance where it is tight or over this month (WO-E), and each network in one line. | { from?, to? } |
web_report | Read | The Website Agent's work report for a range. | { from?, to? } |
performance_rows | Read | Google performance by day: views, clicks, calls, directions; the search terms. | { days?, terms? } |
reports_list | Read | The reports kept for the location. | {} |
report_get | Read | One kept report, with its HTML. | { id } |
Example: The Local Agent's report
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/local_report \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{"from":"2026-11-01","to":"2026-11-09"}'The answer. The Local Agent's work report for the range; the last 30 days to today when from and to are left out.
Your business
What every agent reads about the business: its kind, audience and products, the knowledge (documents, notes and offers) and the reply rules for the inbox and for reviews.
| Operation | Kind | What it does | Params |
|---|---|---|---|
business_profile | Write | Your business: kind, audience, products (read with no changes). | { changes?: { kind?: local | online | hybrid, audience?, products?: string[] } } |
business_knowledge_list | Read | Business knowledge every agent reads: documents, notes, offers. | {} |
business_knowledge_add_note | Write | Add a note to the knowledge (text 10 to 5000 characters; a usp is one line). | { about: services | catalogue | usp | process | terms | faq | other, title?, text } |
business_knowledge_add_offer | Write | Add an offer to the knowledge. | { title, details, terms?, valid_from?, valid_until } |
business_knowledge_remove | Write | Remove a knowledge item. | { context_id } |
business_reply_rules_get | Read | The reply rules for a channel. | { scope: inbox | reviews } |
business_reply_rules_save | Write | Save the reply rules for a channel (one rule a line; replaces them, empty clears). | { scope: inbox | reviews, text } |
Example: The business knowledge
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/business_knowledge_list \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. Business knowledge every agent reads: documents, notes and offers.
The content library and sources
Every creative of the business in one library, and the owner's content sources (feeds).
| Operation | Kind | What it does | Params |
|---|---|---|---|
content_library_list | Read | The content library: every creative of the business. | { kind?: image | video | reel | banner | flyer | gif, agent?: local | social | ads | web, network?, place?, from?: YYYY-MM-DD, to?: YYYY-MM-DD, source?: posted | uploaded | fly | you | creator_hub, before?, limit? } |
content_library_get | Read | One library asset. | { asset_id } |
content_library_keep | Write | Keep a creative in the library. | { ref } |
content_library_remove | Write | Remove a library asset. | { id } | { ref } |
content_sources_list | Read | The owner's content sources (feeds). | {} |
content_source_save | Write | Add or change a content source. | { id?, name, url, format: json | feed, headers?: [{ name, value? }], items_path?, field_map?, per_week?, enabled?: boolean, scope?: location | workspace } |
content_source_test | Write | Test a content source. | { id?, url?, format?: json | feed, headers?, items_path?, field_map? } |
content_source_delete | Write | Delete a content source. | { id } |
Example: The pictures in the library
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/content_library_list \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{"kind":"image","limit":20}'The answer. items, newest first, and next_before for the next page, with the places of the business.
Broadcasts to locations
A business with several locations sends one post, offer or article to all or some of them: make it, approve it, cancel it, and retry one location.
| Operation | Kind | What it does | Params |
|---|---|---|---|
broadcast_list | Read | The business's broadcasts to its locations. | {} |
broadcast_get | Read | One broadcast. | { broadcast_id } |
broadcast_create | Write | Make a broadcast. | { kind: social_post | google_post | offer | article, title?, content: { text, image_url?, link?, offer?: { what, start, end, terms?, code? } }, targets?: all | selected, target_location_ids?, variation?: local_details | per_location_rewrite, approval?: brand | per_location, schedule_at?, source_post_id? } |
broadcast_approve | Write | Approve a broadcast. | { broadcast_id } |
broadcast_cancel | Write | Cancel a broadcast. | { broadcast_id } |
broadcast_item_retry | Write | Retry one location of a broadcast. | { item_id } |
Example: The broadcasts
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/broadcast_list \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. The business's broadcasts to its locations.
What the agents ask before they start
Before an agent starts it asks a few steps. Read them, ask for a step's proposal (AI), and answer each or start.
| Operation | Kind | What it does | Params |
|---|---|---|---|
before_start_state | Write | What the agents ask before they start, with each agent's steps (skip and seed change the steps, so it needs fly:write). | { agents?: [local | web | social | ads | citations], skip?: [products | categories], seed?: true } |
before_start_propose | Write | A step's proposal (AI); step is one of the agent's steps from before_start_state. | { agent: local | web | social | ads | citations, step, q? } |
before_start_answer | Write | Answer a step, or start. | { agent, step, answers?, skipped? } | { start: true, agents? } |
Fly AI credits and settings
Fly AI's credits and their ledger, auto top-up, the models it offers, the person's own Fly AI settings and the WhatsApp numbers that reach it. Nothing is bought here: a top-up is the Billing page's address.
| Operation | Kind | What it does | Params |
|---|---|---|---|
ai_credits_get | Read | The Fly AI credits of the workspace: the balance, this month's free allowance, the least a turn needs, auto top-up. | {} |
ai_ledger | Read | The Fly AI credits ledger, newest first, 50 rows a page at most. | { limit?: 1..50, before?: ISO } |
ai_balances | Read | Every balance of the workspace: the Fly AI credits, the Content agent balance where it is open, and each auto top-up. | {} |
ai_autotopup_get | Read | Auto top-up of the Fly AI credits: on or off, the threshold, the block, whether a card or UPI is saved. | {} |
ai_autotopup_set | Write | Switch auto top-up of a balance on or off, with its threshold and block in minor units (on needs a card or UPI saved on the Billing page). | { kind?: fly_ai_balance | content_balance, on: boolean, threshold_minor?, block_minor? } |
ai_topup_link | Read | The Billing page address where the owner buys a block of a balance; nothing is bought here. | { kind?: fly_ai_balance | content_balance } |
ai_models | Read | The models Fly AI offers, each with its price per million tokens in and out and the cost of a typical ask in dollars, and the rupees a dollar is charged at. | {} |
ai_settings_get | Read | Fly AI's settings for the person: the default location and agent, whether it asks before it changes anything, the model, the effort, the tool calls a reply and the spend cap a reply, with the models it offers. | {} |
ai_settings_set | Write | Change those settings (null or an empty string clears a default; max_tool_calls cleared is 50 again; turn_spend_cap_minor 0 is no cap). | { default_location_id?: uuid | null, default_agent?: local | social | ads | web | citations | manager | null, confirm_writes?: boolean, model?: auto | anthropic/claude-sonnet-5.5 | anthropic/claude-haiku-5.5 | anthropic/claude-opus-5.5 | null, effort?: low | medium | high | null, max_tool_calls?: 1..100, turn_spend_cap_minor?: 100..100000 | 0 | null } |
ai_whatsapp_list | Read | The WhatsApp numbers that reach Fly AI for the person, the account phone among them. | {} |
ai_whatsapp_add | Write | Add a WhatsApp number: a 6 digit code goes to it (the account's verified phone needs none). Only on a connection given every workspace, location and agent. | { phone: E.164, workspace_ids?: uuid[] } |
ai_whatsapp_verify | Write | Verify a number with the code it got. | { id, code } |
ai_whatsapp_remove | Write | Remove a WhatsApp number. | { id } |
Example: The Fly AI credits
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/ai_credits_get \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. currency, free_left_minor, paid_minor, total_minor, the month and its free_allowance_minor, min_turn_minor, autotopup and a line such as "Rs 212 left". Amounts are in minor units (paise or cents).
More operations
Every other operation of this page, as the catalogue lists it.
| Operation | Kind | What it does | Params |
|---|---|---|---|
packs_get | Read | The one-time packs and their orders. | { order_id? } |
plan_move_decide | Write | "Not now" on a plan card. | { action_id, decision: declined } |
ads_review_link | Write | The Ads review board's share link (opens without signing in, read only, nothing can be approved or changed on it): the place's link, reused while it has more than a day left, else a new one for 90 days. | {} |
citations_report | Read | The Listings Agent's work report for a range: where the listings stand, its work, where the business is listed, what needs the owner and what is next. | { from?, to? } |