xMap Flows API reference

Start here

Every request goes to https://flows.xmap.ai/api, sends JSON, and signs in with an access key as a Bearer token.

Get your key. Sign in (or create a free account), open Settings, and under API keys and AI assistants name a key and press Create access key. Copy it straight away: it is shown only once and starts with xfk_.
Try it. Put your key in place of xfk_your_key below. The answer names you and your organizations.

curl https://flows.xmap.ai/api/v1/me \
  -H "Authorization: Bearer xfk_your_key"

The fastest way to use it: build and test a flow in the app, then run it from your system with POST /v1/flows/{id}/run, or give it a Webhook trigger and post your data to its address.

Access keys

Personal keys (Settings, API keys and AI assistants) act as you, with exactly your access. They can be read-only, and end after 30 days, 90 days, a year, or when you delete them.
Organization keys (Team page, Organization API keys; admins only) belong to the organization, keep working when people leave, and act as a member (read and write) or a viewer (read only), never an admin. The activity log names the key.
Keys are shown once. Keep them in your system’s secret settings, never in a web page or a shared document. An organization’s IP allow-list applies to its keys too.

Flows and runs

GET/v1/me

Who the key acts as, and its organizations with their credits.

GET/v1/flows?organization_id={id}

The flows the key can see (the first organization when organization_id is left out): id, name, status (draft, live, done), number of blocks, tags.

POST/v1/flows/{id}/run

Runs a flow. send: true runs it for real: live data, its emails and app messages are sent, credits are used and results are remembered, like Run once in the editor. send: false is a test run that sends nothing. A flow whose trigger is a Webhook takes its items in input.items. The answer has the status (passed, failed, waiting, stopped), each block’s result and credits, and the items that reached the end of the flow (up to 500).

curl -X POST https://flows.xmap.ai/api/v1/flows/FLOW_ID/run \
  -H "Authorization: Bearer xfk_your_key" -H "Content-Type: application/json" \
  -d '{"send": false, "input": {"items": [{"name": "Main store", "lat": 51.507, "lng": -0.128}]}}'

GET/v1/runs/{id}

A run’s status later: useful for runs that wait (a Wait or Approval block) or carry on in parts. Gives the status, when it carries on, each block’s result and a sample of rows.

Your tables (My data)

Tables in My data feed the My data, Find nearest and Match with my table blocks, and the New rows trigger. Send rows from your own systems with an access key.

GET/v1/tables?organization_id={id}

The organization’s tables: id, the setting to use in a block (t:<id>), name, columns and number of rows.

POST/v1/tables

Makes a table from name, columns and rows (lists in the column order, or objects keyed by column), up to 5,000 rows and 40 columns. Columns named lat/lng (or latitude/longitude) give each row its position.

curl -X POST https://flows.xmap.ai/api/v1/tables -H "Authorization: Bearer xfk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "My stores", "columns": ["name", "lat", "lng"], "rows": [["Main store", 51.507, -0.128]]}'

POST/v1/tables/{id}/rows

Adds rows to a table (new columns are added when you send columns). Live flows that start on New rows of this table run on the new rows; the answer says which.

DELETE/v1/tables/{id}

Deletes a table for good, with its rows. Blocks that read it then need another table.

Data on demand

These answers are sample data while live xMap data is connected to the API, and they use no credits. Every answer says so ("sample": true). For live data today, run a flow (the MCP tool list_blocks lists the data blocks that are switched on now).

GET/v1/data

The products and the settings each one takes (no key needed).

POST/v1/data/{product}

scan: places in an area (area.cities, area.countries, area.point {{lat, lng, radius}} or area.geojson; categories, limit up to 500). poi, mobility, traffic: details for the places you send.

curl -X POST https://flows.xmap.ai/api/v1/data/scan -H "Authorization: Bearer xfk_your_key" \
  -H "Content-Type: application/json" -d '{"area": {"cities": ["London"]}, "limit": 20}'

Webhooks

A live flow whose trigger is a Webhook has its own address (shown in the block). Post JSON to it: one object, a list, or a list under items, places, rows, data or records. The address is the secret, so no key is needed; replace it from the block if it leaks.

curl -X POST "https://flows.xmap.ai/api/hook/FLOW_ID/SECRET" -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" -d '{"items": [{"name": "Northside Pharmacy", "city": "Manchester"}]}'

The answer has the run’s status and its results (items, up to 500). Add ?wait=0 to get an answer at once (202) with a status_url to ask for the results when the run is done.
Repeats: a call with the same Idempotency-Key as one in the last day answers with the first run instead of running again. Without a key, two calls with the same body are both run, unless the second arrives while the first is still running (a retry after a timeout): it then answers with the first call’s run (or 409 while it has none yet). Send an Idempotency-Key when your system may send the same event twice.
At most 30 calls a minute per flow; at most 500 items are used.

App events (an “<App> event” block) have their own address, which xMap registers with the app when the flow is deployed and removes when it is paused, archived or deleted. An event the app sends again (the same delivery id within a day, or the same body within an hour) is answered 200 and does not run the flow again. Where the app signs its calls and the block has the secret (WhatsApp’s App Secret, Linear), calls without a valid signature are ignored; otherwise the address is the secret. At most 120 calls a minute per flow.

Signed alerts

A flow’s alerts can post to your address after each real run (its “...” menu, Alerts and exports). Each post carries X-XFlows-Signature: sha256=<HMAC of the body with your secret>. Check it before trusting the post:

import { XMapFlows } from './xmapflows.mjs';
const ok = await XMapFlows.verifySignature(rawBody, req.headers['x-xflows-signature'], process.env.ALERT_SECRET);

Errors and limits

Status	Means
400	Something in the request is not right; `error` says what.
401	No key, a wrong key, or a key that ended.
402	Not enough credits, or the organization’s monthly spending limit.
403	The key may not do this: read-only, a role without that right, or the organization’s rules (such as its networks).
404	Not found, or not yours to see.
429	Too many requests: at most 120 a minute per key. Wait and try again.

Errors are JSON: {"error": "In words", "code": "short_code"}. Runs use the same credits as in the app; each block shows its price in the editor.

Client libraries

One small file each, no dependencies, MIT licence. Copy it into your project. Both retry when the API asks you to slow down, and raise errors with the status and the message.

JavaScript (xmapflows.mjs)Python (xmapflows.py)OpenAPI description

JavaScript (Node 18 or newer)

import { XMapFlows } from './xmapflows.mjs';
const xf = new XMapFlows(process.env.XMAP_FLOWS_KEY);
const [flow] = await xf.flows();
const run = await xf.runFlow(flow.id, { send: true });
console.log(run.status, run.count, run.items.slice(0, 3));

Python (3.8 or newer)

import os
from xmapflows import XMapFlows
xf = XMapFlows(os.environ["XMAP_FLOWS_KEY"])
flow = xf.flows()[0]
run = xf.run_flow(flow["id"], send=True)
print(run["status"], run["count"], run["items"][:3])

AI assistants (MCP)

Claude, ChatGPT, Cursor and other assistants that speak MCP can list, build, check, run and deploy flows at https://flows.xmap.ai/mcp, signed in with the same access keys, or by signing in through the browser (Claude and ChatGPT connectors). Settings, API keys and AI assistants shows ready-to-paste setup, and Connect Claude, ChatGPT or another AI assistant has the steps for Claude and ChatGPT on the web and on phones.

The tools act as you, with exactly your rights in the app (a read-only key lists and reads only):

Flows: list_flows and get_flow (each with its AI employee: the name it goes by, its job, what it works on), create_flow, update_flow (also the AI employee’s own name), update_block, delete_flow, and ask_xmap_ai to build or change a flow in plain words.
Blocks and templates: list_blocks (every block you can add now, its settings and price; blocks and apps xMap switched off or hid are left out, and cannot be added), list_app_actions, list_templates (search the 1,000 templates; one that needs a block switched off is not offered).
Running: check_flow (problems and cost, without running), run_flow (a test, or Run once with send: true), deploy_flow, list_runs, get_run.
AI employees: get_employee (its name and job, timetable, how much it does alone, weekly report card, its budget), rename_employee (its own name, and the flow’s), set_budget (set, raise or take off its monthly budget), set_autonomy (ask me first, act and tell me, or fully on its own), team_inbox, add_to_inbox and reply_to_employee (the AI employees’ notes, any flow added to the Team inbox, and a reply in plain words), weekly_review and review_employee (this week’s review of the AI employees and one decision each: keep, raise, change or let go), team_chart and hand_off (the AI employees as an org chart, who feeds whom; one hands what it finds to another, the words first, then applied or undone), morning_briefing (this morning’s briefing in words: what was found, what needs you, the one thing first).
Results and answers: list_results (the results the AI employees found, with filters; results are found, scored and shown, with no statuses to set), chart_results and pin_chart (a chart of the results from a sentence, pinned to a dashboard), compare_sites (two or three sites side by side: people, rivals, roads, stations, EV charging, hazards, river and sea, air; the best of each row marked and the best site and why; the price first), list_outreach and approve_outreach (Outreach messages waiting for an OK and the sequences running; approve, rewrite or decline them), your_market (Results, Map: every layer of what the AI employees found, with counts, and what changed this week), ask_the_map (a question about places, the price first, then the answer), enrich_table (look each row of a table up once), list_my_data, create_table, add_rows, delete_table, list_maps.
Working together: list_comments, add_comment (pinned to a block, or a reply), resolve_comment, and flow_versions (the saved versions and what changed since one, in words).
Accounts: list_organizations, list_connections, create_connection.

Public addresses (shared links, client views and live feeds for BI tools) are made and stopped in the app, where you see what is shared.

Provisioning (SCIM)

Organizations with single sign-on can let their identity provider add and remove people and push groups, at https://flows.xmap.ai/api/scim/v2/<organization id> (SCIM 2.0, Users and Groups). The token and the exact address are in Settings, Single sign-on.

Questions: chat with support or write to sales@xmap.ai.