Account, home and reports

    Some operations belong to no single agent: the location's home and its cards, the activity and the passes, what you tell the agents, Ask, links, reports, your business, broadcasts and Fly AI.

    Each still runs on one location, named in the path, like every op.

    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.

    1. 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.
    2. Plans, payment and Fly AI credits are bought in the app. ai_topup_link answers the Billing page address and buys nothing. In the app: Billing.

    The working loop

    1. Find the location: GET /v1/workspaces lists each workspace with its locations and their location_id.
    2. Read the home: POST /v1/tools/fly_home with location_id answers every agent's cards that need the owner, the ones in flight, recent activity, rank and health; the op get answers the whole home.
    3. Decide each card: respond with the card's id as action_id and a decision.
    4. Read what was done: work_summary counts what the agent did, runs lists its passes and events the activity trail; each agent's report is under Reports.
    The location's home
    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.

    GET /v1/me
    curl -H "Authorization: Bearer fmk_your_key" https://www.fly-social.com/api/v1/me
    GET /v1/workspaces
    curl -H "Authorization: Bearer fmk_your_key" https://www.fly-social.com/api/v1/workspaces

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

    The home and its cards
    OperationKindWhat it doesParams
    getReadThe agent home: the location, the cards, the activity, rank, health, the plan.{}
    respondWriteApprove, decline, mark done, dismiss, submit or undo a card.{ action_id, decision: approve | reject | done | dismiss | submit | change | undo_dismiss, reply_text?, inputs? }
    fyi_seenWriteGot it on an FYI card.{ action_id }
    card_recheckWriteCheck a finished card against Google again.{ action_id }
    card_recheck_statusReadHow a recheck is going.{ action_id }
    action_statusReadHow the cards this caller raised ended.{}
    changed_atReadWhen the cards, drafts and reviews last changed.{}
    healthReadThe health signals and the worker heartbeat only.{}
    growth_stateReadThe growth loop: what moved and what is lined up.{}
    paused_lineReadThe line held work shows while the agent is paused.{}

    Example: Approve a card

    POST /v1/locations/{location_id}/ops/respond
    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).

    Activity and passes
    OperationKindWhat it doesParams
    eventsReadThe activity trail, a page at a time.{ offset?, limit? }
    event_detailReadOne activity line in full.{ event_id }
    runsReadThe agent passes, newest first.{ limit?, before? }
    tickWriteQueue a pass now, all stages or the named ones (the early access gate may refuse).{ checks?: string[] }
    work_summaryReadCounts of what the agent did, all time and the last 30 days.{ all?: boolean }
    get_dashboard_dataReadThe dashboard numbers for the location.{}

    Example: The activity trail

    POST /v1/locations/{location_id}/ops/events
    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.

    Telling the agent things
    OperationKindWhat it doesParams
    instructionsWriteTell 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 }
    attachWriteSend the agent a picture or a file with an instruction.{ media_kind, instruction, url? }
    content_instructionsWriteThe standing instructions for one kind of content: list them, add one, withdraw one.{ kind: frames | posts } | { kind, add: text } | { kind, remove_id }
    instruction_generaliseWriteTurn a refine instruction into a general rule (AI; saves nothing, answers the rule to offer).{ instruction, source: post_refine | frame_refine }
    instruction_rememberWriteKeep a refine instruction as a standing rule.{ instruction, source: post_refine | frame_refine }

    Example: The standing rules

    POST /v1/tools/fly_instruct
    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.

    Settings
    OperationKindWhat it doesParams
    settingsWriteRead 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_onlyWritePosts 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_accessReadWhich beta agents and staff views this account may see.{}
    setup_dismissWriteDismiss the set-up strip.{}

    Example: Read the settings

    POST /v1/tools/fly_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.

    Notifications
    OperationKindWhat it doesParams
    notificationsReadThe notifications list.{ filter?, offset?, limit? }
    notification_readWriteMark one notification read.{ id } | { all: true }
    notification_read_allWriteMark every notification read.{}

    Example: The notifications

    POST /v1/locations/{location_id}/ops/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.

    Ask the agent
    OperationKindWhat it doesParams
    askReadAsk the agent a question about this location (read only, never acts).{ question }
    ask_sendWriteA line to the agent from the Ask panel: answered from what it knows, or made into work.{ instruction, conversation_id?, new_conversation? }
    ask_conversationsReadThe Ask conversations.{}
    ask_conversationWriteOne conversation (a pending refresh in it is claimed, so it needs fly:write).{ conversation_id }
    ask_refreshWriteRefresh a stale answer (may queue a pass).{ conversation_id, event_id }
    ask_refresh_answerWriteThe refreshed answer (written to the conversation, so it needs fly:write).{ conversation_id, event_id }
    ask_suggestionsReadSuggested asks.{}

    Example: Ask a question

    POST /v1/locations/{location_id}/ops/ask
    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.

    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.

    Reports
    OperationKindWhat it doesParams
    local_reportReadThe Local Agent's work report for a range.{ from?: YYYY-MM-DD, to?: YYYY-MM-DD }
    social_reportReadThe Social Agent's work report for a range.{ from?, to? }
    ads_reportReadThe 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_reportReadThe Website Agent's work report for a range.{ from?, to? }
    performance_rowsReadGoogle performance by day: views, clicks, calls, directions; the search terms.{ days?, terms? }
    reports_listReadThe reports kept for the location.{}
    report_getReadOne kept report, with its HTML.{ id }

    Example: The Local Agent's report

    POST /v1/locations/{location_id}/ops/local_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.

    Your business
    OperationKindWhat it doesParams
    business_profileWriteYour business: kind, audience, products (read with no changes).{ changes?: { kind?: local | online | hybrid, audience?, products?: string[] } }
    business_knowledge_listReadBusiness knowledge every agent reads: documents, notes, offers.{}
    business_knowledge_add_noteWriteAdd 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_offerWriteAdd an offer to the knowledge.{ title, details, terms?, valid_from?, valid_until }
    business_knowledge_removeWriteRemove a knowledge item.{ context_id }
    business_reply_rules_getReadThe reply rules for a channel.{ scope: inbox | reviews }
    business_reply_rules_saveWriteSave the reply rules for a channel (one rule a line; replaces them, empty clears).{ scope: inbox | reviews, text }

    Example: The business knowledge

    POST /v1/locations/{location_id}/ops/business_knowledge_list
    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).

    The content library and sources
    OperationKindWhat it doesParams
    content_library_listReadThe 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_getReadOne library asset.{ asset_id }
    content_library_keepWriteKeep a creative in the library.{ ref }
    content_library_removeWriteRemove a library asset.{ id } | { ref }
    content_sources_listReadThe owner's content sources (feeds).{}
    content_source_saveWriteAdd 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_testWriteTest a content source.{ id?, url?, format?: json | feed, headers?, items_path?, field_map? }
    content_source_deleteWriteDelete a content source.{ id }

    Example: The pictures in the library

    POST /v1/locations/{location_id}/ops/content_library_list
    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.

    Broadcasts to locations
    OperationKindWhat it doesParams
    broadcast_listReadThe business's broadcasts to its locations.{}
    broadcast_getReadOne broadcast.{ broadcast_id }
    broadcast_createWriteMake 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_approveWriteApprove a broadcast.{ broadcast_id }
    broadcast_cancelWriteCancel a broadcast.{ broadcast_id }
    broadcast_item_retryWriteRetry one location of a broadcast.{ item_id }

    Example: The broadcasts

    POST /v1/locations/{location_id}/ops/broadcast_list
    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.

    What the agents ask before they start
    OperationKindWhat it doesParams
    before_start_stateWriteWhat 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_proposeWriteA 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_answerWriteAnswer 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.

    Fly AI credits and settings
    OperationKindWhat it doesParams
    ai_credits_getReadThe Fly AI credits of the workspace: the balance, this month's free allowance, the least a turn needs, auto top-up.{}
    ai_ledgerReadThe Fly AI credits ledger, newest first, 50 rows a page at most.{ limit?: 1..50, before?: ISO }
    ai_balancesReadEvery balance of the workspace: the Fly AI credits, the Content agent balance where it is open, and each auto top-up.{}
    ai_autotopup_getReadAuto top-up of the Fly AI credits: on or off, the threshold, the block, whether a card or UPI is saved.{}
    ai_autotopup_setWriteSwitch 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_modelsReadThe 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_getReadFly 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_setWriteChange 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_listReadThe WhatsApp numbers that reach Fly AI for the person, the account phone among them.{}
    ai_whatsapp_addWriteAdd 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_verifyWriteVerify a number with the code it got.{ id, code }
    ai_whatsapp_removeWriteRemove a WhatsApp number.{ id }

    Example: The Fly AI credits

    POST /v1/locations/{location_id}/ops/ai_credits_get
    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.

    More operations
    OperationKindWhat it doesParams
    packs_getReadThe one-time packs and their orders.{ order_id? }
    plan_move_decideWrite"Not now" on a plan card.{ action_id, decision: declined }
    citations_reportReadThe 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? }