Getting started with the Fly Agents API

    The Fly Agents API lets your own code run the same actions an AI assistant can run on your Fly agents, over HTTPS and JSON. Make a key on the AI assistants page in Fly, send it as a Bearer, and call https://www.fly-social.com/api/v1.

    Make a key

    Sign in to Fly and open AI assistants under Business and settings. Under Agent credentials, give the key a name, choose the workspaces, locations and agents it may reach, and select Make a credential.

    The key starts fmk_ and is shown once, so copy it then. It ends on its day: 90 days when you leave the days empty, 365 at most. Tick Read only for a key that may read but never change anything. Keep it on your server, never in a page or an app people download.

    A key needs a business on a paid Fly plan, or access from Fly. The same key works for AI assistants too.

    The address and a first call

    Every route starts https://www.fly-social.com/api/v1. Send the key in an Authorization header as Bearer with every call. Answers are JSON.

    Start with who the key belongs to: the person, the key's scopes and what it may reach.

    Who the key belongs to
    curl -H "Authorization: Bearer fmk_your_key" https://www.fly-social.com/api/v1/me

    Find your workspaces and locations

    GET /api/v1/workspaces lists the workspaces and locations the key may reach. Each workspace has its workspace_id, name and eligible; each location under it its location_id, name, city and agents_on, the agents switched on there (local, social, ads, web, citations).

    Every call that works on a location names it by that location_id. A workspace with eligible false cannot be worked through the API.

    The workspaces and locations
    curl -H "Authorization: Bearer fmk_your_key" https://www.fly-social.com/api/v1/workspaces

    List the operations

    GET /api/v1/ops answers count and ops: each op with its family, its kind (read or write), what it does and its params. Add family to list one: ads, ask, assistant, bookings, business, citations, home, keywords, links, posts, profile, reports, reviews, settings, social, website.

    GET /api/v1/tools lists the tools the key may call, each with its input schema. A tool does one job with named arguments, such as fly_home for a location's home or fly_report for an agent's report.

    Each agent has a page of its own here with its operations by task, and the reference lists every operation in one table.

    The Ads operations
    curl -H "Authorization: Bearer fmk_your_key" "https://www.fly-social.com/api/v1/ops?family=ads"
    The tools
    curl -H "Authorization: Bearer fmk_your_key" https://www.fly-social.com/api/v1/tools

    Run a read

    POST /api/v1/locations/{location_id}/ops/{op} runs one operation on one location. The JSON body holds its params; an empty body sends none. get is the agent home: the location, the cards waiting for you, the activity, rank and health.

    An op's answer is the op's own JSON, whole, after location with the location's id and name.

    The API keeps no current location: name it on every call. A tool, run with POST /api/v1/tools/{tool}, takes location_id in its body.

    The agent home of a location
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/get \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -d '{}'
    The same home through the fly_home tool
    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"}'

    Run a write, once

    A write needs a key without Read only. Approving a card is a write: respond takes the card id as action_id and a decision.

    Add an Idempotency-Key header to a write: 1 to 128 visible ASCII characters, new for each change you mean. If the same key comes again from the same credential within 24 hours, nothing runs again: the answer is 409 idempotency_conflict with the first call's status and time, or in_progress while the first call still runs. Without the header, every call runs as sent.

    So after a timeout or a dropped connection, send the same call with the same key again: it runs once at most.

    A call refused before anything ran, such as one missing a param, gives its key back, so the corrected call may send the same key.

    Approve a card, once
    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"}'

    From your own code

    The same read from Node 18 or newer, the key kept in FLY_API_KEY in your server's environment. Read error.code, not the message: the codes stay, the words may change.

    Node
    const res = await fetch('https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/get', {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.FLY_API_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({}),
    });
    const answer = await res.json();
    if (res.status >= 400) throw new Error(`${answer.error.code}: ${answer.error.message} (request ${answer.error.request_id})`);

    Routes

    RouteKeyWhat it does
    GET /api/v1NoThe API's name and version, and where its docs and the OpenAPI document are.
    GET /api/v1/openapi.jsonNoThe OpenAPI 3.1 document, every action as a path.
    GET /api/v1/meYesWho the key belongs to, its scopes and its access.
    GET /api/v1/workspacesYesThe workspaces and locations the key may reach, with the location ids.
    GET /api/v1/ops?family=YesThe actions, with their kind and params. family is optional.
    GET /api/v1/toolsYesThe tools the key may call, with their input schemas.
    POST /api/v1/locations/{location_id}/ops/{op}YesRun an action on a location. The body is its params.
    POST /api/v1/tools/{tool}YesRun a tool. The body is its arguments, location_id among them.

    The operations of each agent, by task: the developer pages. Every operation in one table: the reference.

    Errors and their codes

    An answer that is not a success carries one error object with a code, a message and a request_id. Every answer, success or not, carries an X-Request-Id header with the same id. Some refusals carry more under error.details, such as the answer the agent sent.

    An error
    {
      "error": {
        "code": "no_location",
        "message": "Name the location: an op takes it in its path, a tool takes location_id in its body. GET /v1/workspaces lists them.",
        "request_id": "a1b2c3d4e5f6"
      }
    }
    Statuserror.codeWhat it means
    400params, not_json, statelessThe params are not right (the message says which), the body is not a JSON object, or fly_use_location was called: name the location on every call instead.
    401no_token, invalid_tokenNo key, or a key that has ended or was revoked.
    403insufficient_scopeA read only key asked for a write.
    403op_denied, share_page, held_grantThe action stays in the Fly app. The message says why.
    403app_grantThe token is the one Fly AI uses inside the app, which does not open the API. Make a key on the AI assistants page.
    403no_location, outside_grant, not_allowed, not_eligible, agent_not_grantedNo location was named, or it is outside the key's access, no longer yours to act on, not on a paid plan, or needs an agent the key was not given.
    404not_foundNo such route, action or tool.
    405method_not_allowedThe route takes the other method; the Allow header names it.
    409idempotency_conflict, in_progressThe Idempotency-Key was used in the last 24 hours. Nothing ran again.
    413too_largeThe call ran, but its answer is over 4,000,000 bytes, so it is not returned: ask for less with the op's own paging or filters. If it changed something, the change is made: do not send it again. A body you send may be 256 KB at most; over that, nothing runs.
    429rate_limitedOver the limit. Wait the seconds in the Retry-After header.
    5xxserver_errorSomething failed on Fly's side or in the agent. Send the request_id when you write to us.

    Limits

    • Each key may make 120 calls a minute and 3,000 a day. An AI assistant on the same key counts against the same limit.
    • An answer comes back whole, up to 4,000,000 bytes.
    • Whatever a call changes goes through the same checks, mode and plan limits as the app, and shows on Activity.

    Long calls

    An action may take up to two minutes. Let your client wait 120 seconds before it gives up, and send writes with an Idempotency-Key so a retry is safe.

    The OpenAPI document

    The OpenAPI 3.1 document at https://www.fly-social.com/api/v1/openapi.json holds every action as a path, with what it does and its params. It needs no key, so a code generator or an AI coding assistant can read it.

    https://www.fly-social.com/api/v1/openapi.json

    What stays in the app

    These stay in the Fly app, as they do for AI assistants:

    • Paying, plans and slots
    • Cancelling a plan
    • Adding or removing locations
    • Connecting Google, social, ad or website accounts

    For these, open the page in the app. The connect links an owner hands to whoever manages the accounts come from the fly_connect_links tool.