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.
curl -H "Authorization: Bearer fmk_your_key" https://www.fly-social.com/api/v1/meFind 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.
curl -H "Authorization: Bearer fmk_your_key" https://www.fly-social.com/api/v1/workspacesList 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.
curl -H "Authorization: Bearer fmk_your_key" "https://www.fly-social.com/api/v1/ops?family=ads"curl -H "Authorization: Bearer fmk_your_key" https://www.fly-social.com/api/v1/toolsRun 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.
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 '{}'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.
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.
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
| Route | Key | What it does |
|---|---|---|
GET /api/v1 | No | The API's name and version, and where its docs and the OpenAPI document are. |
GET /api/v1/openapi.json | No | The OpenAPI 3.1 document, every action as a path. |
GET /api/v1/me | Yes | Who the key belongs to, its scopes and its access. |
GET /api/v1/workspaces | Yes | The workspaces and locations the key may reach, with the location ids. |
GET /api/v1/ops?family= | Yes | The actions, with their kind and params. family is optional. |
GET /api/v1/tools | Yes | The tools the key may call, with their input schemas. |
POST /api/v1/locations/{location_id}/ops/{op} | Yes | Run an action on a location. The body is its params. |
POST /api/v1/tools/{tool} | Yes | Run 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.
{
"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"
}
}| Status | error.code | What it means |
|---|---|---|
| 400 | params, not_json, stateless | The 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. |
| 401 | no_token, invalid_token | No key, or a key that has ended or was revoked. |
| 403 | insufficient_scope | A read only key asked for a write. |
| 403 | op_denied, share_page, held_grant | The action stays in the Fly app. The message says why. |
| 403 | app_grant | The token is the one Fly AI uses inside the app, which does not open the API. Make a key on the AI assistants page. |
| 403 | no_location, outside_grant, not_allowed, not_eligible, agent_not_granted | No 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. |
| 404 | not_found | No such route, action or tool. |
| 405 | method_not_allowed | The route takes the other method; the Allow header names it. |
| 409 | idempotency_conflict, in_progress | The Idempotency-Key was used in the last 24 hours. Nothing ran again. |
| 413 | too_large | The 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. |
| 429 | rate_limited | Over the limit. Wait the seconds in the Retry-After header. |
| 5xx | server_error | Something 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.
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.