Local Agent API

    The Local Agent runs the Google Business Profile of a location: it keeps the profile complete, answers reviews, writes posts every week and reads where the location ranks on the map grid.

    Through the API your code reads and changes what it does, one location at a time: the profile and its photos, posts and frames, reviews and the review link, the search terms it tracks and bookings.

    What the Local Agent does and its plan

    The Local Agent plan, one for each location. The price is on the plans page.

    New to the API? Start with Getting started: the key, the address, the errors and the limits.

    Getting started with this agent

    These are done in the Fly app, signed in, because the API cannot do them.

    1. Add the location in the app: connect its Google Business Profile on Google's own screen. The API cannot connect an account. connect_link, or the tool fly_connect_links with kinds set to ["google"], gives a fresh connect link to hand to the owner. In the app: Locations.
    2. Choose the Local Agent plan for the location. Plans and payment stay in the app. In the app: Billing.
    3. Make a key on the AI assistants page and give it the Local Agent. A key held to other agents answers agent_not_granted here. In the app: AI assistants.
    4. Pick how much the agent does on its own with the settings op on the account page: changes.autonomy is approve_required (Fly asks first), auto_safe (Fly does the routine) or full_auto (Fly does it all).

    The working loop

    1. Find the location: GET /v1/workspaces lists each location with its location_id; agents_on holds "local" where the Local Agent is switched on.
    2. Read the agent's home: POST /v1/tools/fly_home with location_id and agent "local" answers the Local Agent's cards that need the owner (cards.needs_you), the ones in flight, its recent activity, rank and health.
    3. Decide each card: POST /v1/locations/{location_id}/ops/respond with the card's id as action_id and a decision (approve, reject, done, dismiss, submit, change or undo_dismiss). The tool fly_card gives one card whole first.
    4. Read its report: POST /v1/tools/fly_report with agent "local" and from and to dates (YYYY-MM-DD) answers the headline numbers, each section and the first rows of each table; the op local_report on the account page answers the report whole.
    The Local Agent'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","agent":"local"}'

    Read the Google profile

    Start here to see the profile as the agent sees it: the audit and what to fix, every change the agent made, the history of changes by the agent, the owner and Google, and the services and attributes on Google.

    Read the Google profile
    OperationKindWhat it doesParams
    get_optimize_dataReadThe profile audit: scores and what to fix.{}
    agent_changesReadEvery change the agent made on the profile, grouped.{}
    profile_changes_listReadChanges on the profile over time: the agent's, the owner's, Google's.{ offset?, limit? }
    get_gbp_servicesReadThe services on the Google profile.{}
    get_gbp_attributesReadThe attributes on the Google profile.{}

    Example: The profile audit

    POST /v1/locations/{location_id}/ops/get_optimize_data
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/get_optimize_data \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -d '{}'

    The answer. The profile audit: the scores and what to fix, after location with its id and name.

    Change the Google profile

    profile_field_set changes one basic, such as the phone, website, description or hours, through a card the agent applies. Services and attributes are saved as a whole list, the list get_gbp_services and get_gbp_attributes read. undo_change takes back a change the agent made on Google.

    Change the Google profile
    OperationKindWhat it doesParams
    profile_field_setWriteChange a basic on the Google profile: phone, website, description, hours, and more (a card the agent applies).{ field, value }
    save_gbp_servicesWriteSave the services (the whole list as the page sends it).{ services: [{ ... isEnabled }] }
    save_gbp_attributesWriteSave the attributes (the whole list).{ attributes: [...] }
    service_scheduleWriteAdd services to the profile one at a time, on a schedule or by the agent.{ services, mode, at? }
    undo_changeWriteUndo a change the agent made on Google.{ action_id }

    Example: Change the website on the profile

    POST /v1/locations/{location_id}/ops/profile_field_set
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/profile_field_set \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: website-2026-11-10-1" \
      -d '{"field":"website","value":"https://www.example.com"}'

    The answer. action_id (the card the change is recorded as), run_id and message: the change is sent to Google and the agent confirms it on Activity within a minute.

    Words and ideas the agent writes

    Each of these asks the agent for words or ideas (AI): a description, three description angles, categories, services and a service description, cover designs and a product card.

    Words and ideas the agent writes
    OperationKindWhat it doesParams
    description_suggestWriteA description for the profile (AI).{}
    description_variantsWriteThree description angles (AI).{}
    category_suggestWriteCategories the agent suggests (AI).{}
    service_suggestWriteServices the agent suggests (AI).{ round?: saved | new, exclude?: string[], existing?: string[] }
    service_describeWriteA description for one service (AI).{ name }
    branding_designWriteThree cover designs on the cover photo card (AI).{ action_id }
    product_cardWriteThe product card's picture and words (AI).{ action_id }

    Profile Guard

    Profile Guard watches the protected fields (phone, website, name, description and regular hours) against their master values. guard_get reads it, guard_set switches it and sets each field, and guard_rollback puts one field back on Google now.

    Profile Guard
    OperationKindWhat it doesParams
    guard_getReadProfile Guard for the location: on or off, each protected field with its master value, the value on Google now and its mode, the owners and managers on Google (the expected ones marked), the verification reason with what to do, and the last 50 events.{ refresh?: boolean }
    guard_setWriteSwitch Profile Guard on or off, set a field's master value (Keep the change sets the new value) or its mode (rollback puts it back automatically where safe, watch only reports), the expected owners and managers, or the weekly roll back cap. Switched on the first time, the master values are taken from Google.{ enabled?: boolean, fields?: { phone | website | name | description | regular_hours: { golden?, mode?: rollback | watch } }, expected_admins?: [{ admin_key, admin?, role }], rollback_cap_per_week?: 0 to 10 }
    guard_rollbackWritePut one protected field back to its master value on Google now (a person's roll back of a change Profile Guard held).{ field: phone | website | name | description | regular_hours }

    Example: Profile Guard at the location

    POST /v1/locations/{location_id}/ops/guard_get
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/guard_get \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -d '{}'

    The answer. Whether it is on, each protected field with its master value, its value on Google now and its mode, the owners and managers on Google, the verification reason and the last 50 events.

    Photos and reference photos

    The photo library and what went to Google, photos added by address and scheduled to Google, and the reference photos the agent draws from.

    Photos and reference photos
    OperationKindWhat it doesParams
    get_photosReadThe photo library and what went to Google.{}
    profile_photosReadThe photos on the profile and the ones waiting.{}
    photos_to_libraryWriteAdd photos by URL to the library.{ photos: [{ url, category, scheduled_for? }] }
    photo_scheduleWriteList the scheduled photos, or schedule photos to Google.{ mode: list } | { photos: [{ url, category }], mode: schedule | agent | cadence, at?, every_days? }
    delete_photoWriteRemove a photo from the library.{ photo_id }
    references_listReadThe reference photos and their categories.{}
    reference_addWriteAdd a reference photo by its picture address in Fly storage.{ category_id (from references_list), title, reference_role: practitioner | staff | interior | exterior | product | other, description, person_name? (required for practitioner and staff), usage_instructions?, image_url, usage_mode?: reference | ready_to_post }
    reference_tagWriteTag a reference photo.{ reference_id, reference_role: practitioner | staff | interior | exterior | product | other, description, person_name? (required for practitioner and staff), usage_instructions? }
    reference_removeWriteRemove a reference photo.{ reference_id }
    photos_to_profileWriteSend reference photos to the Google profile.{ reference_ids: string[] }

    Example: The photo library

    POST /v1/locations/{location_id}/ops/get_photos
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/get_photos \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -d '{}'

    The answer. The photo library and what went to Google.

    Reviews and their replies

    The agent drafts a reply to each review. review_queue_list reads the reviews waiting and the drafts; review_queue_decide sends or ignores them, one by one or all waiting; review_queue_edit puts your own words on a draft.

    Reviews and their replies
    OperationKindWhat it doesParams
    review_queue_listReadThe reviews waiting for a reply and the replies drafted.{ view?, offset?, limit? }
    review_queue_decideWriteSend or ignore drafted replies.{ review_row_ids | all_waiting: true, decision: send | ignore }
    review_queue_editWriteEdit a drafted reply.{ review_row_id, draft }
    review_queue_redraftWriteDraft a reply again (AI).{ review_row_id }
    review_reply_refineWriteTell the agent how to change a reply on a card.{ action_id, instruction }
    review_replies_recentReadThe recent replies.{}
    review_reply_timesReadWhen the reply runs go.{}

    Example: The reviews waiting for a reply

    POST /v1/locations/{location_id}/ops/review_queue_list
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/review_queue_list \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -d '{"limit":20}'

    The answer. items (the reviews and their drafted replies), counts, has_more for the next page, and writing: the reviews whose replies are still being written.

    How the agent replies

    The reply rules and mode, and the review responder settings.

    How the agent replies
    OperationKindWhat it doesParams
    review_policy_getReadThe agent's reply rules and mode.{}
    review_policy_saveWriteSave the reply rules.{ policy, source? }
    get_review_settingsReadThe review responder settings.{}
    save_review_settingsWriteSave the review responder settings.{ ...settings }

    Example: The reply rules

    POST /v1/locations/{location_id}/ops/review_policy_get
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/review_policy_get \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -d '{}'

    The answer. policy (the saved rules, or null), suggested (what the form opens with), mode, line, counts and unanswered_recent.

    Posts: the agent's drafts

    The agent writes post drafts for the owner to review. Read them with drafts, then approve or reject each with idea_decision, ask for a change with idea_feedback or idea_revise, and move or withdraw one. posts_generate asks for more, and topics_check checks typed topics first.

    Posts: the agent's drafts
    OperationKindWhat it doesParams
    draftsReadThe post drafts waiting for review, as cards.{}
    idea_for_editorReadA draft's words and picture for editing.{ idea_id }
    idea_decisionWriteApprove or reject a draft; approve with publish to post it now or at a time (two hours ahead at least), else the agent picks the time.{ idea_id, decision: approve | reject, publish?: { mode: now | at, at?: ISO } }
    idea_feedbackWriteAsk for a change on a draft: the words, the picture or both.{ idea_id, feedback, target: words | picture | both }
    idea_reviseWriteChange the words of a draft with an instruction.{ idea_id, instruction }
    idea_rescheduleWriteMove a scheduled or approved draft to a new time (two hours ahead at least).{ idea_id, scheduled_at: ISO }
    idea_withdrawWriteTake a draft back: cancel its schedule or delete it.{ idea_id, mode: cancel | delete }
    draft_dateWritePick the day (or the day and time) a waiting draft goes out; a day that has a post already asks confirm_shared.{ idea_id, day: YYYY-MM-DD, confirm_shared?: boolean } | { idea_id, at: ISO, confirm_shared?: boolean }
    draft_buttonWriteThe button on one draft (every button but NONE and CALL needs its url).{ idea_id, type: NONE | LEARN_MORE | BOOK | ORDER | SHOP | SIGN_UP | CALL, url? }
    draft_frameWriteChoose the frame for one draft.{ idea_id, frame_id }
    done_postsReadThe drafts the owner has answered.{}
    held_postsReadThe approved posts the agent is holding, with why.{}
    posts_generateWriteWhat is being written now ({}), ask for a week, a month or a range of posts, or ask for one post per typed topic on its date (check them with topics_check first).{} | { from, to, kind: week | month | custom, count? } | { topics: [{ date, topic, repeat_ok?, off_service_ok? }] }
    topics_checkReadCheck typed post topics before asking for them: which repeat a post from the last 90 days, which name none of the listed services, and the days that already hold a draft.{ from, to, topics: [{ topic, date? }] }

    Example: Approve a draft

    POST /v1/locations/{location_id}/ops/idea_decision
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/idea_decision \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: idea-5c2e8f14-approve-1" \
      -d '{"idea_id":"5c2e8f14-7a3b-4d9e-a1c6-2b8d4f0e6a93","decision":"approve"}'

    The answer. ok and the decision. Without publish the agent picks the time; publish with mode at and a time two hours ahead at least posts it then.

    Posts you make

    Make a Google post now or at a time, to the connected social networks too with social_targets. Check calendar first so a post is not booked twice. A post you made moves with post_reschedule and is cancelled with post_cancel until it goes out.

    Posts you make
    OperationKindWhat it doesParams
    calendarReadThe content calendar: published, scheduled, approved and draft posts by day (62 days at most).{ from: YYYY-MM-DD, to: YYYY-MM-DD }
    write_postWriteWords for a post from a brief or a rough draft (AI).{ text, post_type?: STANDARD | OFFER | EVENT, rewrite?: shorter | warmer | formal | cta }
    create_postWriteMake a Google post now or at a time; to the connected social networks too (social_targets are the social_account_id values from social_targets).{ summary, type?: STANDARD | EVENT | OFFER, media_urls?: string[], call_to_action?, event_info?, offer_info?, scheduled_at?: ISO, content_idea_id?, social_targets?: social_account_id[], to_google?: boolean }
    post_rescheduleWriteMove a post you made that has not gone out to a new time, ten minutes ahead at least: its Google post and its social posts.{ post_id, scheduled_at: ISO }
    post_cancelWriteCancel a post you made (fly_post_create or the New post page) that has not gone out: its Google post and its social posts.{ post_id }
    button_contextReadThe links a post button may point at.{}
    post_draftsReadThe New post page's own saved drafts.{}
    post_draft_getReadOne saved New post draft.{ draft_id }
    post_draft_saveWriteSave a New post draft.{ draft_id, state, step?, networks? }
    post_draft_deleteWriteDelete a saved New post draft.{ draft_id }

    Example: Schedule a post

    POST /v1/locations/{location_id}/ops/create_post
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/create_post \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: post-winter-hours-1" \
      -d '{"summary":"Our winter hours start on Monday: 9 am to 7 pm, every day.","type":"STANDARD","scheduled_at":"2026-11-20T10:00:00+05:30"}'

    The answer. ok and the post_id, the id post_reschedule and post_cancel take; social when it goes to social networks too.

    Frames

    The frame every post is drawn in: the frames the business may post in, the one in use, a preview, and the frames the image model designs for the business.

    Frames
    OperationKindWhat it doesParams
    framesReadThe frames the business may post in.{}
    frame_in_useReadThe frame in use.{}
    frame_setWriteSet the frame every post uses (null for none).{ template_id | null }
    frame_previewWriteDraw a picture (in Fly storage) inside a frame, a preview; with no frame named, the frame in use.{ image_url, model_frame_id? | template_id?, fit?: whole }
    model_framesReadThe frames the image model designed for the business.{}
    model_frames_generateWriteDesign new frames for the business (AI, counts on the plan).{ source?: settings | onboarding }
    model_frame_chooseWriteChoose one designed frame.{ frame_id }
    model_frame_refineWriteRefine a designed frame with an instruction.{ frame_id, instruction }

    Example: The frames

    POST /v1/locations/{location_id}/ops/frames
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/frames \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -d '{}'

    The answer. The frames the business may post in.

    The month's offer

    The month's offer post: read it, give the owner's own offer, answer the offer card's inputs, schedule it and change its words or picture.

    The month's offer
    OperationKindWhat it doesParams
    offer_getReadThe month's offer post.{ month?: YYYY-MM }
    offer_createWriteThe owner's own offer for a month.{ month, offer_what, offer_terms?, offer_start, offer_end, offer_code?, offer_link? }
    offer_submitWriteSubmit the offer card's inputs.{ action_id, inputs: { offer_running: yes | no | suggest, offer_what?, offer_start?: YYYY-MM-DD, offer_end?: YYYY-MM-DD, offer_terms?, offer_code?, offer_link? } }
    offer_scheduleWriteSchedule the offer post.{ action_id, title, summary, start, end, code?, link?, terms?, image_url?, no_image? }
    offer_changeWriteChange the offer post's words or picture.{ action_id, target: words | picture | both, instruction, title?, summary? }
    offer_change_statusReadHow an offer change is going.{ action_id }
    offer_title_suggestWriteA title for an offer (AI).{ text?, caption?, topic? }

    Example: December's offer post

    POST /v1/locations/{location_id}/ops/offer_get
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/offer_get \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -d '{"month":"2026-12"}'

    The answer. The month's offer post.

    Search terms on the map grid

    The search terms the agent tracks on the map grid, with their ranks and history. Add, change or stop tracking one.

    Search terms on the map grid
    OperationKindWhat it doesParams
    get_keywords_dataReadThe tracked search terms with their map grid ranks and history.{}
    add_keywordWriteTrack a search term on the map grid.{ keyword }
    edit_keywordWriteChange a tracked search term.{ keyword_id, keyword }
    remove_keywordWriteStop tracking a search term.{ keyword_id }
    get_keyword_recommendations_contextReadWhat the agent knows for suggesting search terms.{}

    Example: The tracked search terms

    POST /v1/locations/{location_id}/ops/get_keywords_data
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/get_keywords_data \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -d '{}'

    The answer. The tracked search terms with their map grid ranks and history.

    Bookings

    The month's bookings, a booking added by hand, and the booking link: your own, or Fly's.

    Bookings
    OperationKindWhat it doesParams
    bookingsReadThe month's bookings.{ month: YYYY-MM }
    booking_addWriteAdd a booking by hand.{ name, phone?, email?, date, time, service?, note?, notify? }

    Example: November's bookings

    POST /v1/locations/{location_id}/ops/bookings
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/bookings \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -d '{"month":"2026-11"}'

    The answer. The month's bookings.

    More operations

    Every other operation of this page, as the catalogue lists it.

    More operations
    OperationKindWhat it doesParams
    done_cardsReadEvery finished card, page by page (send next_before back as before for the next page).{ before?: ISO, limit?: 1..60 }
    festivals_getReadThe festivals month posts are made for: the well-known list for the business's country, or the workspace's own list.{}
    festivals_setWriteKeep the workspace's own festival list for the business's country, or go back to the well-known list. Signed-in callers only.{ use_own, festivals: [name] }
    plan_usageReadThe posts and frames the plan has left this month.{}