What the Listings Agent does and its plan
The Listings 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.
- Choose the Listings Agent plan for the location. In the app: Billing.
- Make a key on the AI assistants page and give it the Listings Agent. In the app: AI assistants.
- Switch it on for the location with the
settingsop on the account page:changes.enabled_checks.citations_agentset to true. - Give it what a directory asks for. Numbers and answers go in with
citations_shelf_put; files go in on the Listings page in the app. In the app: Listings (/app/l/{location_id}/listings).
The working loop
- Find the location:
GET /v1/workspaceslists each location with itslocation_id;agents_onholds"citations"where the Listings Agent is switched on. - Read the agent's home:
POST /v1/tools/fly_homewithlocation_idandagent"citations"answers the Listings 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 where it stands:
citations_plan_getanswers the plan, the directories chosen and the state of each;citations_detaileach listing. The Listings Agent has nofly_reportof its own.
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":"citations"}'The plan: which directories
The Listings Agent's plan is the directories chosen and the state of each. Research the directories worth listing on, choose them, take on the ones a card offered, and add or remove a directory of your own by its address.
| Operation | Kind | What it does | Params |
|---|---|---|---|
citations_plan_get | Read | The Listings Agent's plan: the directories chosen and their state. | { part?: overview } |
citations_plan_research | Write | Research the directories worth listing on. | {} |
citations_plan_select | Write | Choose the directories. | { selected: string[] } |
citations_plan_fill | Write | Take on the directories a card offered. | {} |
citations_source_add | Write | Add a directory by URL. | { url, name? } |
citations_source_remove | Write | Remove a directory you added by URL, while the agent has not started on it (its id from citations_plan_get). | { source_id } |
Example: The plan
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/citations_plan_get \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. The Listings Agent's plan: the directories chosen and their state.
The listings and the questions it stops on
Each directory listing and its state. When a directory asks for a code, a yes or a password, the agent stops and asks: answer it with citations_ask_answer. citations_place_again starts or retries a directory; the owner must be around for the code the site sends.
| Operation | Kind | What it does | Params |
|---|---|---|---|
citations_detail | Read | The directory listings and their state. | {} |
citations_ask_answer | Write | Answer a question the agent stopped on: a code, a yes, a password. | { source_id, ask_id, value } |
citations_place_again | Write | Start a directory the agent has not started on, or try one again (the owner must be around for the code the site sends). | { source_id } |
citations_request_decline | Write | "I do not have this". | { source_id, key } |
Example: The listings
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/citations_detail \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. The directory listings and their state.
Documents and answers you give it
The shelf holds the documents and answers the owner gave the agent. Give a number or an answer, or take one off.
| Operation | Kind | What it does | Params |
|---|---|---|---|
citations_shelf_get | Read | The documents and answers the owner gave the Listings Agent. | {} |
citations_shelf_put | Write | Give a number or an answer (files go through the app). | { type, kind: number | answer, value, question? } |
citations_shelf_remove | Write | Remove one from the shelf. | { type } |
Example: The shelf
curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/citations_shelf_get \
-H "Authorization: Bearer fmk_your_key" \
-H "Content-Type: application/json" \
-d '{}'The answer. The documents and answers the owner gave the Listings Agent.
More operations
Every other operation of this page, as the catalogue lists it.
| Operation | Kind | What it does | Params |
|---|---|---|---|
citations_pictures | Read | The last pictures the agent took at a place. | { source_id, limit?: 1..12 } |