Developer API

On Elite, Master and Ultimate plans, the Subscriber Exchange can be read programmatically. It is designed for members who run their own Telegram bot and want their exchange numbers inside it — a channel's hosting activity, a campaign's placements and clicks, a reach estimate before submitting.

Telegram bot integrations only, for now

This is stated on the Developer API card itself: the Subscriber Exchange API can currently be used to power Telegram bot integrations only. Website and other server-to-server integrations are not supported yet. If you are building on a website, hold off connecting until we announce support.

Availability

Plan	Developer API	API keys	Requests per minute
Free, Lite, Plus	Not included	—	—
Elite	Included	2	60
Master	Included	5	120
Ultimate	Included	10	300

Your own ceilings are shown on the card, so you never have to guess: "Up to N keys · N requests/min."

If your plan does not include the API, the Developer API card does not appear on the exchange hub at all.

Creating a key

1. Open the exchange page at https://onflowads.com/telegram/dashboard/subscriber-exchange.
2. Scroll to the Developer API card on the hub.
3. Click Create a key.
4. Name it when prompted — something that will still mean something in six months, for example "server" or "analytics".
5. The key is shown once, in a copy prompt: "Copy your key now — it won't be shown again." Copy it and store it somewhere safe.

Keys begin with sx_. After creation the card lists each key by its name and a short prefix, along with how many calls it has made.

A key is a password

Anyone holding your key can read your exchange data and cancel your campaigns. Never paste it into a public repository, a chat, or client-side code. If a key is exposed, revoke it immediately and create a new one.

If Create a key is greyed out

You are at your plan's key ceiling. Revoke a key you no longer use, or move up a plan.

Revoking a key

1. Find the key on the Developer API card.
2. Click Revoke on its row.
3. Confirm: "Revoke this key? Anything using it stops working immediately."

Revocation is instant and cannot be undone. The key stays listed for your records, marked as revoked.

Making a request

Send a POST to /api/subx/v1 with your key and an action. The key can be presented three ways — pick whichever suits your client:

• as a bearer token in the Authorization header,
• in an X-Api-Key header,
• or as a key field in the request body.

A minimal request body looks like this:

{
  "key": "sx_your_key_here",
  "action": "state"
}

Every response carries an ok field. Failures return ok: false with a human-readable error.

Available actions

Action	What it returns
ping	A liveness check. Useful for confirming a key works.
state	Your entitlements (plan, capacity, targeting dimensions, credit balance, what one extra placement costs, how many you could afford), your reliability score and the exchange's minimum, your standing (strikes, cooldown), whether you are currently eligible, and live pool counts.
channels	Your enrolled channels, with their level ceiling, status, hosting counts and host controls.
ads	All your campaigns, each with its status, mode, delivery upgrade, targeting and metrics.
ad	One campaign in full. Pass ad set to its public id.
reach	An estimate of eligible channels. Pass a level, and optionally niche, languages, countries and size_bands. Returns the pool at that level and how many match your targeting.
cancel	Cancels a campaign. Pass the campaign's public id. Behaves exactly like the dashboard's Cancel — future placements stop, anything live finishes its 24 hours.

An unrecognised action returns: "Unknown action. Use ping / state / channels / ads / ad / reach / cancel."

What the API deliberately will not do

Two operations stay on the dashboard on purpose, and both return a clear message pointing you back there:

Action	Response
create	"Ad creation runs in the dashboard, where the wallet charge and moderation live. The API lists, inspects, estimates reach and cancels."
veto / unveto	"Host veto runs on the dashboard (it also takes the live copy down). Use the exchange page."

Both involve something that should never happen by accident: creating an ad can charge your wallet and spend your credits, and refusing an ad takes a live post down in someone's channel. Those belong on a screen where you can see what you are about to do.

Limits and error responses

Situation	HTTP status	What it means
Missing or unrecognised key	401	"Invalid API key." Check the key, and that it has not been revoked.
Too many requests	429	"Rate limit exceeded." You have passed your plan's per-minute allowance. Back off and retry.
Bad or missing parameter	422	The message names the parameter, for example "Pass a content level (1–5)."
Not found	404	Usually a campaign id that isn't yours.
Temporarily unavailable	503	"Service unavailable." Retry shortly.

Anonymity holds on the API too

The API returns the same shapes the dashboard receives, and it honours the same rules. Nothing it returns can tell you which channels carried your ad, and nothing it returns can tell a host who wrote an ad they carried.

That extends to one detail you might otherwise expect back: a campaign's blocked-channel list is never echoed, because it is the only field that names channels — returning it would turn your own blocklist into a way of confirming which handles are enrolled. You get the count instead.

FAQ

Can I use one key for several bots?

You can, but separate keys are better: you can revoke one without breaking the others, and each key's call count is tracked separately.

Does using the API count against anything else?

Only the per-minute rate on that key. It has no effect on your placements, credits or reliability.

I lost my key. Can I see it again?

No. Keys are shown once at creation and never again. Revoke the old one and create a replacement.

Does the API work on a lapsed subscription?

Your entitlements return to Free-level numbers when a subscription lapses, and the Free plan does not include the API — so key-authed requests stop working until you renew. Campaigns already running keep the allowance they were submitted with.

---

Next: Rules and fair play — the six rules every member follows, and exactly what happens when one is broken.