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.
- 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 toolfly_connect_linkswithkindsset to["google"], gives a fresh connect link to hand to the owner. In the app: Locations. - Choose the Local Agent plan for the location. Plans and payment stay in the app. In the app: Billing.
- Make a key on the AI assistants page and give it the Local Agent. A key held to other agents answers
agent_not_grantedhere. In the app: AI assistants. - Pick how much the agent does on its own with the
settingsop on the account page:changes.autonomyisapprove_required(Fly asks first),auto_safe(Fly does the routine) orfull_auto(Fly does it all).
The working loop
- Find the location:
GET /v1/workspaceslists each location with itslocation_id;agents_onholds"local"where the Local Agent is switched on. - Read the agent's home:
POST /v1/tools/fly_homewithlocation_idandagent"local"answers the Local Agent's cards that need the owner (cards.needs_you), the ones in flight, its recent activity, rank and health. - Decide each card:
POST /v1/locations/{location_id}/ops/respondwith the card'sidasaction_idand adecision(approve,reject,done,dismiss,submit,changeorundo_dismiss). The toolfly_cardgives one card whole first. - Read its report:
POST /v1/tools/fly_reportwithagent"local"andfromandtodates (YYYY-MM-DD) answers the headline numbers, each section and the first rows of each table; the oplocal_reporton the account page answers the report whole.
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.
| Operation | Kind | What it does | Params |
|---|---|---|---|
get_optimize_data | Read | The profile audit: scores and what to fix. | {} |
agent_changes | Read | Every change the agent made on the profile, grouped. | {} |
profile_changes_list | Read | Changes on the profile over time: the agent's, the owner's, Google's. | { offset?, limit? } |
get_gbp_services | Read | The services on the Google profile. | {} |
get_gbp_attributes | Read | The attributes on the Google profile. | {} |
category_search | Read | Search Google's category list. | { q } |
Example: The profile audit
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.
| Operation | Kind | What it does | Params |
|---|---|---|---|
profile_field_set | Write | Change a basic on the Google profile: phone, website, description, hours, and more (a card the agent applies). | { field, value } |
save_gbp_services | Write | Save the services (the whole list as the page sends it). | { services: [{ ... isEnabled }] } |
save_gbp_attributes | Write | Save the attributes (the whole list). | { attributes: [...] } |
service_schedule | Write | Add services to the profile one at a time, on a schedule or by the agent. | { services, mode, at? } |
undo_change | Write | Undo a change the agent made on Google. | { action_id } |
Example: Change the website on the profile
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.
| Operation | Kind | What it does | Params |
|---|---|---|---|
description_suggest | Write | A description for the profile (AI). | {} |
description_variants | Write | Three description angles (AI). | {} |
category_suggest | Write | Categories the agent suggests (AI). | {} |
service_suggest | Write | Services the agent suggests (AI). | { round?: saved | new, exclude?: string[], existing?: string[] } |
service_describe | Write | A description for one service (AI). | { name } |
branding_design | Write | Three cover designs on the cover photo card (AI). | { action_id } |
product_card | Write | The 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.
| Operation | Kind | What it does | Params |
|---|---|---|---|
guard_get | Read | Profile 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_set | Write | Switch 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_rollback | Write | Put 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
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.
| Operation | Kind | What it does | Params |
|---|---|---|---|
get_photos | Read | The photo library and what went to Google. | {} |
profile_photos | Read | The photos on the profile and the ones waiting. | {} |
photos_to_library | Write | Add photos by URL to the library. | { photos: [{ url, category, scheduled_for? }] } |
photo_schedule | Write | List the scheduled photos, or schedule photos to Google. | { mode: list } | { photos: [{ url, category }], mode: schedule | agent | cadence, at?, every_days? } |
delete_photo | Write | Remove a photo from the library. | { photo_id } |
references_list | Read | The reference photos and their categories. | {} |
reference_add | Write | Add 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_tag | Write | Tag a reference photo. | { reference_id, reference_role: practitioner | staff | interior | exterior | product | other, description, person_name? (required for practitioner and staff), usage_instructions? } |
reference_remove | Write | Remove a reference photo. | { reference_id } |
photos_to_profile | Write | Send reference photos to the Google profile. | { reference_ids: string[] } |
Example: The photo library
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.
| Operation | Kind | What it does | Params |
|---|---|---|---|
review_queue_list | Read | The reviews waiting for a reply and the replies drafted. | { view?, offset?, limit? } |
review_queue_decide | Write | Send or ignore drafted replies. | { review_row_ids | all_waiting: true, decision: send | ignore } |
review_queue_edit | Write | Edit a drafted reply. | { review_row_id, draft } |
review_queue_redraft | Write | Draft a reply again (AI). | { review_row_id } |
review_reply_refine | Write | Tell the agent how to change a reply on a card. | { action_id, instruction } |
review_replies_recent | Read | The recent replies. | {} |
review_reply_times | Read | When the reply runs go. | {} |
Example: The reviews waiting for a reply
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.
| Operation | Kind | What it does | Params |
|---|---|---|---|
review_policy_get | Read | The agent's reply rules and mode. | {} |
review_policy_save | Write | Save the reply rules. | { policy, source? } |
get_review_settings | Read | The review responder settings. | {} |
save_review_settings | Write | Save the review responder settings. | { ...settings } |
Example: The reply rules
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.
Getting more reviews: the review link and QR code
The link and QR code a customer opens to leave a review, how it is doing and the reviews that came through it.
| Operation | Kind | What it does | Params |
|---|---|---|---|
review_generator_get | Read | The review link and QR code. | {} |
review_generator_create | Write | Make the review link and QR code. | {} |
review_generator_update | Write | Change the review link's settings. | { ...settings } |
review_generator_stats | Read | How the review QR is doing. | {} |
review_generator_reviews | Read | The reviews that came through the link. | {} |
Example: The review link
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/review_generator_get \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. The review link and QR code.
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.
| Operation | Kind | What it does | Params |
|---|---|---|---|
drafts | Read | The post drafts waiting for review, as cards. | {} |
idea_for_editor | Read | A draft's words and picture for editing. | { idea_id } |
idea_decision | Write | Approve 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_feedback | Write | Ask for a change on a draft: the words, the picture or both. | { idea_id, feedback, target: words | picture | both } |
idea_revise | Write | Change the words of a draft with an instruction. | { idea_id, instruction } |
idea_reschedule | Write | Move a scheduled or approved draft to a new time (two hours ahead at least). | { idea_id, scheduled_at: ISO } |
idea_withdraw | Write | Take a draft back: cancel its schedule or delete it. | { idea_id, mode: cancel | delete } |
draft_date | Write | Pick 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_button | Write | The 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_frame | Write | Choose the frame for one draft. | { idea_id, frame_id } |
done_posts | Read | The drafts the owner has answered. | {} |
held_posts | Read | The approved posts the agent is holding, with why. | {} |
posts_generate | Write | What 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_check | Read | Check 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
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.
| Operation | Kind | What it does | Params |
|---|---|---|---|
calendar | Read | The content calendar: published, scheduled, approved and draft posts by day (62 days at most). | { from: YYYY-MM-DD, to: YYYY-MM-DD } |
write_post | Write | Words for a post from a brief or a rough draft (AI). | { text, post_type?: STANDARD | OFFER | EVENT, rewrite?: shorter | warmer | formal | cta } |
create_post | Write | Make 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_reschedule | Write | Move 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_cancel | Write | Cancel 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_context | Read | The links a post button may point at. | {} |
post_drafts | Read | The New post page's own saved drafts. | {} |
post_draft_get | Read | One saved New post draft. | { draft_id } |
post_draft_save | Write | Save a New post draft. | { draft_id, state, step?, networks? } |
post_draft_delete | Write | Delete a saved New post draft. | { draft_id } |
Example: Schedule a 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.
| Operation | Kind | What it does | Params |
|---|---|---|---|
frames | Read | The frames the business may post in. | {} |
frame_in_use | Read | The frame in use. | {} |
frame_set | Write | Set the frame every post uses (null for none). | { template_id | null } |
frame_preview | Write | Draw 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_frames | Read | The frames the image model designed for the business. | {} |
model_frames_generate | Write | Design new frames for the business (AI, counts on the plan). | { source?: settings | onboarding } |
model_frame_choose | Write | Choose one designed frame. | { frame_id } |
model_frame_refine | Write | Refine a designed frame with an instruction. | { frame_id, instruction } |
Example: The 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.
| Operation | Kind | What it does | Params |
|---|---|---|---|
offer_get | Read | The month's offer post. | { month?: YYYY-MM } |
offer_create | Write | The owner's own offer for a month. | { month, offer_what, offer_terms?, offer_start, offer_end, offer_code?, offer_link? } |
offer_submit | Write | Submit 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_schedule | Write | Schedule the offer post. | { action_id, title, summary, start, end, code?, link?, terms?, image_url?, no_image? } |
offer_change | Write | Change the offer post's words or picture. | { action_id, target: words | picture | both, instruction, title?, summary? } |
offer_change_status | Read | How an offer change is going. | { action_id } |
offer_title_suggest | Write | A title for an offer (AI). | { text?, caption?, topic? } |
Example: December's offer post
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.
| Operation | Kind | What it does | Params |
|---|---|---|---|
get_keywords_data | Read | The tracked search terms with their map grid ranks and history. | {} |
add_keyword | Write | Track a search term on the map grid. | { keyword } |
edit_keyword | Write | Change a tracked search term. | { keyword_id, keyword } |
remove_keyword | Write | Stop tracking a search term. | { keyword_id } |
get_keyword_recommendations_context | Read | What the agent knows for suggesting search terms. | {} |
Example: The tracked search terms
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.
| Operation | Kind | What it does | Params |
|---|---|---|---|
bookings | Read | The month's bookings. | { month: YYYY-MM } |
booking_add | Write | Add a booking by hand. | { name, phone?, email?, date, time, service?, note?, notify? } |
booking_link_change | Write | Use your own booking link, or Fly's. | { action_id, url } | { action_id, fly: true } |
Example: November's 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.
| Operation | Kind | What it does | Params |
|---|---|---|---|
done_cards | Read | Every finished card, page by page (send next_before back as before for the next page). | { before?: ISO, limit?: 1..60 } |
festivals_get | Read | The festivals month posts are made for: the well-known list for the business's country, or the workspace's own list. | {} |
festivals_set | Write | Keep 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_usage | Read | The posts and frames the plan has left this month. | {} |