Listings Agent API

    The Listings Agent lists a location on the directories chosen for its trade and city, brings the listings it already has up to date and checks every one each month.

    Through the API your code reads its plan and each listing, chooses the directories, answers the questions it stops on and gives it the numbers and answers it needs.

    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.

    1. Choose the Listings Agent plan for the location. In the app: Billing.
    2. Make a key on the AI assistants page and give it the Listings Agent. In the app: AI assistants.
    3. Switch it on for the location with the settings op on the account page: changes.enabled_checks.citations_agent set to true.
    4. 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

    1. Find the location: GET /v1/workspaces lists each location with its location_id; agents_on holds "citations" where the Listings Agent is switched on.
    2. Read the agent's home: POST /v1/tools/fly_home with location_id and agent "citations" answers the Listings 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 where it stands: citations_plan_get answers the plan, the directories chosen and the state of each; citations_detail each listing. The Listings Agent has no fly_report of its own.
    The Listings 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":"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.

    The plan: which directories
    OperationKindWhat it doesParams
    citations_plan_getReadThe Listings Agent's plan: the directories chosen and their state.{ part?: overview }
    citations_plan_researchWriteResearch the directories worth listing on.{}
    citations_plan_selectWriteChoose the directories.{ selected: string[] }
    citations_plan_fillWriteTake on the directories a card offered.{}
    citations_source_addWriteAdd a directory by URL.{ url, name? }
    citations_source_removeWriteRemove 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

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

    The listings and the questions it stops on
    OperationKindWhat it doesParams
    citations_detailReadThe directory listings and their state.{}
    citations_ask_answerWriteAnswer a question the agent stopped on: a code, a yes, a password.{ source_id, ask_id, value }
    citations_place_againWriteStart 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_declineWrite"I do not have this".{ source_id, key }

    Example: The listings

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

    Documents and answers you give it
    OperationKindWhat it doesParams
    citations_shelf_getReadThe documents and answers the owner gave the Listings Agent.{}
    citations_shelf_putWriteGive a number or an answer (files go through the app).{ type, kind: number | answer, value, question? }
    citations_shelf_removeWriteRemove one from the shelf.{ type }

    Example: The shelf

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

    More operations
    OperationKindWhat it doesParams
    citations_picturesReadThe last pictures the agent took at a place.{ source_id, limit?: 1..12 }