Get the calling app

GET https://api.flow.engineer/v0/app Try it

Returns the app, account and API key that made the request, and the mode it runs in. Useful to check a key and to read the app's pinned API version. plans lists the paid plans (Shared, Dedicated), the Outbound add-on, their prices and the link where the workspace owner buys one (upgrade_url).

Authorizations

Authorizationstringheaderrequired

An API key of one app, sent as Authorization: Bearer <key>. Keys start with fk_test_ (test mode: sandbox senders and test data only) or fk_live_ (live mode). Keep live keys on your server; never ship them in an app or page.

Headers

Flow-Versionstring<date>

The API version to use, as a date. Without it, the version pinned to your app when it was created is used.

Response

200 application/json

The calling app.

account Account required

A customer company. Holds the plan, billing and members. Every app belongs to one account.

Show child attributes

id string required

An account ID, acct_ and a ULID.

Pattern: ^acct_[0-9A-HJKMNP-TV-Z]{26}$

name string required

The company's name.

plan enum<string> required

The account's plan, bought by the workspace owner in the Flow dashboard (https://flow.engineer/dashboard/plans; GET /v0/app's plans lists what is on sale, with prices). Each plan caps how many people your apps may talk with per channel; people shows the caps and what is used. Replies count: a person your app replies to is one of the people counted.

• free: the free trial, 25 people per channel across all the account's apps (not per day or month).
• shared: Flow's shared senders, with caps per channel a day and a month (200 a day and 300 a month today).
• dedicated: your own iMessage line, with a daily cap on it and no monthly cap (1,000 people a day today; a new line starts at 250 a day and ramps to 1,000 over its first 14 days); on Flow's shared senders it has shared's caps, counted apart (people shows each pool).

The numbers are settings and may change; read the caps that apply now from people, not from this list.

• pro, business, enterprise: older plans, kept for accounts that have them; they have no people caps.

New values may be added; treat one you do not know like free.

Available options: free, shared, dedicated, pro, business, enterprise

people PeopleLimits read-only

The account's plan caps on people, and what is used now. A person counts once in a window, with their first inbound message in it on that channel's sender, whether one-to-one or in a group chat. Replies count: a person your app replies to is one of the people counted. Group members who never write, and calls, do not count. On a dedicated iMessage line, the line's own daily limit of different people counts everyone it messages, replies and starts alike (Account.plan). A person past a cap is held: their messages are kept but not delivered to your app, and are delivered once a place frees or the window rolls over. Absent when the account's plan has no people caps. These numbers are the source of truth for the caps; they are settings and can change.

Show child attributes

per enum<string> required

channel: each channel has its own caps (every plan today). account: one set of caps over all channels, with no channel on its entry.

Available options: channel, account

channels ChannelPeople[] required

One entry per channel the caps apply to (one entry without channel when per is account).

Show child attributes

channel enum<string>

A messaging channel. sms is US SMS and MMS (in pilot), from dedicated numbers only.

Available options: telegram, whatsapp, imessage, sms

pool enum<string> required

shared: Flow's shared senders on this channel. own: the account's own senders on it (a dedicated line, its own bot or number). Counted apart.

Available options: shared, own

limits PeopleWindow[] required

Each window the plan caps (free: total; shared: day and month; dedicated: day).

Show child attributes

window enum<string> required

total: since the account began (never resets). day: the UTC day. month: the UTC calendar month.

Available options: total, day, month

limit integer required

How many people may write in the window.

Range: 0 to any

used integer required

How many distinct people wrote in the window so far.

Range: 0 to any

resets_at string<date-time>

When the window rolls over and used starts again. Absent for total.

held integer required

People held now because a cap is reached; their messages wait and are delivered when a place frees or the window rolls over.

Range: 0 to any

hipaa boolean read-only

true when the account is marked as handling protected health information. Its messages then go only through the channels this setting allows (SMS): sends, typing, read receipts and sender connections on Telegram, WhatsApp and iMessage answer 403 permission with channel_code hipaa_channel_not_covered, and messages already queued there fail the same way. The sandbox senders answer the account's contacts with a fixed refusal and store and deliver nothing they send; turning the flag on ends the account's sandbox joins. Only SMS can be simulated (POST /v0/test/conversations): creating a simulated Telegram, WhatsApp or iMessage conversation, or posting a turn to one made before the flag was set, answers the same refusal. Set by the Flow team.

created_at string<date-time> required

When the account was created.

app App required

One agent integration. Owns API keys (per mode), webhook endpoints and settings.

Show child attributes

id string required

An app ID, app_ and a ULID.

Pattern: ^app_[0-9A-HJKMNP-TV-Z]{26}$

account string required

An account ID, acct_ and a ULID.

Pattern: ^acct_[0-9A-HJKMNP-TV-Z]{26}$

name string required

The app's name.

api_version string<date> required

The API version pinned to the app when it was created, used when a request sends no Flow-Version.

settings AppSettings required

Per-app behaviour. The Flow team sets it for now; ask them to change it.

Show child attributes

transcription boolean required

On by default. When on, Flow transcribes the voice notes your app receives on WhatsApp, Telegram and simulated senders, and on iMessage when iMessage made no transcript of its own, and puts the text in the voice content's transcript (transcript_source flow) before it delivers message.received. Both modes are covered, within Flow's limits: a voice note longer than 10 minutes, or one past the app's 4 hours of transcribed audio a day (UTC), arrives without a transcript. Off, voice notes arrive with the audio only; on iMessage a voice note still carries the transcript iMessage made of it, whatever this setting says. Audio files sent as basic media and videos are never transcribed.

auto_read boolean required

When on, Flow marks inbound messages as read as soon as your endpoint accepts them.

sandbox_join_code string

The app's sandbox join code on its own: two words and eight digits, for example brave-otter-40718263. A contact joins this app by sending a shared sandbox sender the join message, which ends with this code in brackets after ref (Join Sandbox app (ref brave-otter-40718263)), or on Telegram by opening the bot's link with the code (https://t.me/<bot>?start=brave-otter-40718263, which sends /start brave-otter-40718263). Each shared sender's join_code gives the whole message: show that to testers, not this code.

created_at string<date-time> required

When the app was created.

api_key ApiKey required

An API key's record. The key itself is shown once, at creation, and stored only as a hash.

Show child attributes

id string required

An API key's ID, key_ and a ULID. Not the secret key itself.

Pattern: ^key_[0-9A-HJKMNP-TV-Z]{26}$

mode enum<string> required

test (sandbox senders and test data only) or live.

Available options: test, live

last4 string required

The key's last four characters, to tell keys apart.

Length: 4 to 4

created_at string<date-time> required

When the key was created.

expires_at string<date-time>

When the key stops working. Set only on keys of an unclaimed app made with POST /v0/sandbox/keys (7 days after it was made); signing in through the device flow claims the app and removes it. An expired key can still start that sign-in for 30 days after this time, and claiming the app within those 30 days makes the key work again.

livemode boolean required

true for a live key, false for a test key.

allowance SandboxAllowance

What the app may still send on the shared sandbox senders for free. Present only on apps that have one: apps made with POST /v0/sandbox/keys (anonymous, one allowance per app), and apps of people who signed in (signed_in, one allowance per person: every app the person owns or claimed draws on the same contacts and messages, so the counts here are the person's, over all those apps). Only messages your agent sends count, on the channels in channels; inbound messages are free. A contact counts once it joins an app on a sandbox sender, and keeps counting after it leaves. Sends past the allowance answer 403 permission with channel_code sandbox_allowance_used; a join past contacts.limit is refused in the chat. Absent on an account with the free trial (your own account, from your first sign-in), which replaces it, and on paid plans.

Show child attributes

tier enum<string> required

anonymous: an app made without an account, whose keys expire. signed_in: an app of a person who signed in (with a Flow account).

Available options: anonymous, signed_in

scope enum<string> required

Who the counts belong to. app: this app alone (anonymous). person: the signed-in person, shared by every app they own or claimed, so sends from their other apps use the same contacts and messages.

Available options: app, person

channels enum<string>[] required

The sandbox channels the allowance covers whose shared sandbox is open now (Telegram today; WhatsApp when its sandbox opens). Shared senders of other channels (iMessage) are not part of it and refuse its sends.

contacts AllowanceCount required

Contacts the allowance has room for, and how many have joined (with scope person, over all the person's apps).

Show child attributes

limit integer required

How many contacts may join on the sandbox (1 for an anonymous app; 3 for a signed-in person, over all their apps).

Range: 0 to any

used integer required

How many have joined so far.

Range: 0 to any

messages_per_contact integer required

How many messages may be sent to each contact (50 anonymous, so 50 in total; 100 signed in).

Range: 0 to any

messages AllowanceMessages required

Messages sent against the allowance, over all its contacts (with scope person, from all the person's apps).

Show child attributes

limit integer required

contacts.limit times messages_per_contact.

Range: 0 to any

used integer required

Messages sent so far on the allowance's sandbox senders.

Range: 0 to any

remaining integer required

Messages still allowed, counting each contact's own cap and the contacts that may still join.

Range: 0 to any

expires_at string<date-time>

anonymous only: when the app's keys expire. Signing in removes it.

upgrade string required

One sentence saying how to raise the allowance, for example by signing in with npx @flow-engineer/messaging login.

plans PlanCatalog read-only

The Flow Messaging plans on sale, the add-on, the account's plan now, and where to buy. Plans are self-serve and live at once (Dedicated after Flow's review of the line): only the workspace owner buys or changes one, in the Flow dashboard (Settings → Usage and billing, or upgrade_url); an API key cannot. Prices and caps are today's; the caps that apply to this account now are in Account.people. When a trial or plan is full, give upgrade_url to the person who owns the workspace. Present on every answer of the current service.

Show child attributes

current string required

The account's plan now, as in Account.plan (free is the free trial).

next enum<string>

The plan that lifts the account's caps next: shared from the free trial, dedicated from Shared. Absent when no bigger plan is on sale.

Available options: shared, dedicated

upgrade_url string<uri> required

The Flow dashboard's Plans dialog, with next picked (?plan=shared, ?plan=dedicated), or with nothing picked when there is no next. Only the workspace owner can buy there.

offers PlanOffer[] required

The plans on sale, smallest first.

Show child attributes

plan enum<string> required

The plan's value in Account.plan.

Available options: shared, dedicated

name string required

The plan's name as the dashboard shows it.

usd_per_month integer required

The price in US dollars a month, billed monthly.

Range: 0 to any

people PlanPeopleCap[] required

The plan's caps on different people, per channel: Shared's on Flow's shared senders, Dedicated's on its own iMessage line (on Flow's shared senders Dedicated has Shared's caps). An empty list is no cap.

Show child attributes

window enum<string> required

day: the UTC day. month: the UTC calendar month.

Available options: day, month

limit integer required

How many different people.

Range: 1 to any

includes string required

One sentence saying what the plan gives.

url string<uri> required

The dashboard's Plans dialog with this plan picked.

add_ons PlanAddOn[] required

The add-ons on sale, each bought on top of a plan.

Show child attributes

add_on enum<string> required

The add-on: outbound, writing first on a dedicated iMessage line.

Available options: outbound

name string required

The add-on's name as the dashboard shows it.

usd_per_month integer required

The price in US dollars a month, on top of the plan.

Range: 0 to any

plans string[] required

The plans it can be added to.

includes string required

One sentence saying what the add-on gives.

url string<uri> required

The dashboard's Plans dialog where it is added.

400 application/json

The request is malformed or a parameter is invalid (invalid_request). error.param names the parameter. Every endpoint answers this for a Flow-Version header that is not a date this API serves (param Flow-Version), and every POST that takes an Idempotency-Key for a key over 255 characters (param Idempotency-Key).

error ErrorBody required

The details of an error.

Show child attributes

type enum<string> required

What went wrong. A closed list: new types arrive only with a new API version. Each type has a page at https://api.flow.engineer/docs/errors/<type>, given in the error's doc_url; the error's hint says what to change for the case.

• invalid_request (400, or 413 for a request body over the size limit): the request is malformed or a parameter is invalid. Fix the parameter named in param; the hint says what it must look like. Every endpoint answers it for a Flow-Version header that is not a version this API serves.
• authentication (401): the API key is missing, malformed, unknown, revoked or expired. An Authorization: Bearer header with nothing after it usually means the environment variable holding the key was empty when the header was built (for an MCP client, when the server was added): the hint says so. Send Authorization: Bearer fk_test_... or fk_live_... with a current key; with no key at all, get a test key with POST /v0/sandbox/keys. A sandbox key past its expires_at has channel_code sandbox_key_expired: sign in to claim the app, or get a new key.
• permission (403): the key may not do this, for example a test key using a live sender, a sandbox contact who joined another app, a new conversation from an iMessage line that may only reply, or a send past the app's sandbox allowance (channel_code sandbox_allowance_used, sandbox_contact_limit or sandbox_channel_not_included). Use the key of the right mode, have the contact send your join message, wait for the contact to message the line first, or sign in through the device flow to lift the allowance. On SMS: contact_opted_out (the contact texted STOP; nothing more goes to them until they text START), consent_required (a start to someone who never texted your numbers: record their consent with consent on the start). In a HIPAA account: hipaa_channel_not_covered (the account's HIPAA setting does not allow the channel; use SMS). Simulated conversations: simulated_contact (a real sender was pointed at a simulated contact; reply in the contact's simulated conversation), not_simulated (a simulated sender or test endpoint was pointed at a real contact), test_mode_only, simulated_conversation_limit. In message.failed: sandbox_contact_left (the contact joined another app on the sandbox sender while the message was queued; have them send your join message again).
• not_found (404): no such object for this app and mode. Check the ID's prefix and that it was made with a key of the same mode (test and live data are separate).
• idempotency_conflict (409): the idempotency key was used for a different request (channel_code body_mismatch: use a new key), or that request is still running (in_progress: wait retry_after seconds and repeat it with the same key), or it already created a secret that is shown only once (secret_not_kept: creating a webhook endpoint, rotating its secret, connecting a WhatsApp number; a secret that was lost must be rotated again, and a WhatsApp number connected again to see its verify token).
• outside_window (409, or in message.failed): the channel will not deliver outside its conversation window. On WhatsApp the 24-hour window is closed: send a template (POST /v0/conversations/{conversation_id}/template, or POST /v0/messages with kind template to start), or wait for the contact to write. On iMessage the contact has not messaged the line (or opted in) yet, so the failure arrives as a message.failed event: wait for the contact to write, then reply in that conversation. iMessage has no 24-hour window: once someone has texted your line, your agent can message them any time. Typing and read receipts answer 409 outside_window directly when the channel's window for them is closed; ignore it and send your reply. On iMessage typing and read receipts work only in a two-way conversation, for 5 minutes after your line's last message to the contact, so send your reply first. On WhatsApp read receipts go at any time. On SMS, channel_code quiet_hours: the contact has not texted in the last hour and it is inside the sender's quiet hours in their time zone; retry after retry_after seconds, or wait for them to text. In message.failed: window_closed (WhatsApp's 24-hour window closed while the message was queued; send a template) and queued_too_long (the message waited in the queue longer than its sender allows, for example while the sender was paused; send it again if it still applies).
• unsupported_content (422): the conversation's channel does not take this kind, field, block or value, and nothing was sent; Flow never converts a message. param names what was refused: kind (the endpoint's kind is not on this channel, such as a carousel on Telegram), a field or block (reply_to on SMS, telegram on WhatsApp, telegram.is_big), or the field whose value is not taken (emoji outside Telegram's reaction emoji, buttons for more than 3 WhatsApp buttons). channel is the conversation's channel and hint says what to send instead over plain HTTP; each endpoint's page lists its channels. In an iMessage group conversation, a reaction, typing or a read receipt answers it with param kind and channel_code group_unsupported: leave it out. Removing a reaction on iMessage (emoji null) when you have none on the message answers it with param emoji and channel_code no_reaction_to_remove: iMessage removes a reaction by naming it. Media to an SMS number without MMS answers it with param media and channel_code no_mms. An edit or unsend of an iMessage message that went by SMS or RCS (its network) answers it with channel_code not_on_sms: send a new message instead. An edit or unsend past the channel's time limit answers it with channel_code edit_window_closed or unsend_window_closed (iMessage: edits within 15 minutes of sending, unsends within 2 minutes; Telegram: unsends within 48 hours), and an iMessage edit of the message that started the conversation with first_message_not_editable; message states the limit and how long ago the message was sent. Send a new message instead. POST /v0/files answers it for a type Flow does not take (programs, web pages, unknown types). A send by file_id of a document a contact sent before Flow malware-scanned documents answers it too: Flow sends only documents it scanned. Flow's template on the shared WhatsApp sandbox sender answers it with param params.body[0] and channel_code template_value_not_taken when your message has a line break or tab, more than four spaces in a row, or makes the template longer than WhatsApp's 1024 characters: write it as one shorter line.
• new_contact_limit (429): the sender has used its budget for starting conversations. Wait retry_after seconds; replies into existing conversations still go.
• sender_throttled (429): abuse signals tripped (the same text to many new contacts, many starts with no reply, blocks), so the sender may not start conversations until retry_after; replies into existing conversations still go. Personalise first messages and start only conversations people expect.
• file_blocked (422): the file failed the malware scan and was not stored. Send a different file. (When the scan cannot run at all, the upload answers a retryable 500 api_error with Retry-After instead.)
• rate_limited (429): either too many requests for this key (the per-key request limit, reported in the RateLimit-* headers) or sends faster than the sender's sending rate (pacing). Wait Retry-After (retry_after) seconds and retry with the same Idempotency-Key. On Flow's shared WhatsApp sandbox sender, channel_code flow_template_limit: your app already sent Flow's template to this contact in the last 24 hours; wait for them to reply, or send it after retry_after seconds.
• channel_error (502, or in message.failed): the channel refused or failed the message, or timed out; channel_code carries its own code. Read message, change what the channel objected to, and send again. From typing and read receipts, which call the channel at once, it is safe to ignore. SMS codes are Flow's, the same whichever carrier network carries the message: carrier_filtered (a carrier's spam filter blocked it: make it read like a person's message, no shortened links), unreachable, invalid_number, landline, registration_required (the number's 10DLC or toll-free registration is not approved yet), carrier_error, and provider_not_configured (the SMS sender is not fully set up on Flow's side, so nothing was sent; contact the Flow team). Flow's own codes on every channel: channel_timeout_unknown_outcome (in message.failed: the channel did not answer after the message was sent, and the resends its policy allows did not settle it, so the message may have arrived or not; check with the contact before sending it again) and unknown_outcome (from typing and read receipts: the call timed out after it was sent).
• not_implemented (501): this endpoint or channel is not live yet during the beta. Use a channel that is live (Telegram, iMessage), or check the changelog.
• api_error (500, 503): something went wrong on Flow's side. Retry with the same idempotency key after retry_after seconds, and quote request_id if it persists.

Available options: invalid_request, authentication, permission, not_found, idempotency_conflict, outside_window, unsupported_content, new_contact_limit, sender_throttled, file_blocked, rate_limited, channel_error, not_implemented, api_error

message string required

A sentence for a developer saying what went wrong. Do not parse it; switch on type.

hint string required

One sentence saying what to change to make the request succeed, specific to this case, for example "Send a template instead: POST /v0/conversations/{conversation_id}/template." For unsupported_content it says what to send instead over plain HTTP. Written for developers and coding agents alike. Do not parse it; it may be reworded at any time.

doc_url string<uri> required

The documentation page for this error's type, https://api.flow.engineer/docs/errors/<type>. It says what the error means, why it happens and how to fix it, with code.

param string

The request parameter the error is about, as a dotted path (kind, telegram.is_big, buttons, cards[1].header.type, limit).

retry_after integer

Seconds to wait before retrying, for errors that clear by themselves.

Range: 0 to any

channel enum<string>

The conversation's channel, on errors about what it takes (unsupported_content) and its windows (outside_window).

Available options: telegram, whatsapp, imessage, sms

conversation string

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

sender string

A sender ID, snd_ and a ULID.

Pattern: ^snd_[0-9A-HJKMNP-TV-Z]{26}$

channel_code string

For channel_error, the channel's own error code, as given by the channel. For some other errors, Flow's own code naming the case, for example sandbox_allowance_used (permission: the sandbox allowance is used up), sandbox_contact_limit (permission: the allowance has no room for another contact), sandbox_channel_not_included (permission: the allowance does not cover this sandbox channel), sign_in_required (permission: an app made without an account cannot do this) or sandbox_key_expired (authentication: a key from POST /v0/sandbox/keys passed its expires_at; permission, for a send that carries no key, such as a reply in a webhook answer, from such an app). For idempotency_conflict, always one of body_mismatch (the key was used for a different request), in_progress (the first request is still running; retry_after says when to repeat it) or secret_not_kept (its answer carried a secret shown only once). SMS: contact_opted_out and consent_required (permission), quiet_hours (outside_window, with retry_after), and carrier_filtered, unreachable, invalid_number, landline, registration_required, carrier_error and provider_not_configured (channel_error). HIPAA accounts: hipaa_channel_not_covered (permission). Connecting your own WhatsApp number (POST /v0/senders): whatsapp_token_malformed, whatsapp_token_rejected, whatsapp_app_secret_malformed and whatsapp_number_not_in_account (invalid_request), and whatsapp_number_taken, whatsapp_account_taken and whatsapp_number_managed (permission). Simulated conversations (permission): test_mode_only, not_simulated, simulated_contact and simulated_conversation_limit. For a message that failed after it was queued (message.failed): sandbox_contact_left (permission), window_closed and queued_too_long (outside_window), and channel_timeout_unknown_outcome (channel_error: the channel never confirmed the send, so it may or may not have arrived). iMessage (permission): imessage_not_granted (the account has no access to Flow's shared line: sign in at flow.engineer to start the free trial). Paid plans (permission): plan_people_limit (a send to a person the account's plan holds: the plan had no room for new people on that channel when they wrote; see Account.people, and GET /v0/app's plans for the bigger plan). plan_ended (authentication for a live key, permission for a live send: the account's paid plan ended, so its live keys and sends are paused until the workspace owner chooses a plan again; test keys keep working). imessage_only (retired 27 Oct 2026; no longer sent: shared lines fall back to SMS/RCS). iMessage (unsupported_content): group_unsupported (a reaction, typing or a read receipt in a group conversation; param kind) and not_on_sms (an edit or unsend of a message that went by SMS or RCS; param kind) and line_contact_card_dedicated_only (imessage.line_contact_card on a shared line; param imessage.line_contact_card). SMS (unsupported_content): no_mms (media to a number without MMS; param media). Edits and unsends (unsupported_content): edit_window_closed and unsend_window_closed (the message is older than the channel allows for the change) and first_message_not_editable (iMessage: the message that started the conversation). From typing and read receipts, unknown_outcome (channel_error: the call timed out after it was sent).

request_id string

Flow's ID for this request. Quote it when asking for help.

401 application/json

The API key is missing, malformed, unknown, revoked or expired (authentication).

error ErrorBody required

The details of an error.

Show child attributes

type enum<string> required

What went wrong. A closed list: new types arrive only with a new API version. Each type has a page at https://api.flow.engineer/docs/errors/<type>, given in the error's doc_url; the error's hint says what to change for the case.

• invalid_request (400, or 413 for a request body over the size limit): the request is malformed or a parameter is invalid. Fix the parameter named in param; the hint says what it must look like. Every endpoint answers it for a Flow-Version header that is not a version this API serves.
• authentication (401): the API key is missing, malformed, unknown, revoked or expired. An Authorization: Bearer header with nothing after it usually means the environment variable holding the key was empty when the header was built (for an MCP client, when the server was added): the hint says so. Send Authorization: Bearer fk_test_... or fk_live_... with a current key; with no key at all, get a test key with POST /v0/sandbox/keys. A sandbox key past its expires_at has channel_code sandbox_key_expired: sign in to claim the app, or get a new key.
• permission (403): the key may not do this, for example a test key using a live sender, a sandbox contact who joined another app, a new conversation from an iMessage line that may only reply, or a send past the app's sandbox allowance (channel_code sandbox_allowance_used, sandbox_contact_limit or sandbox_channel_not_included). Use the key of the right mode, have the contact send your join message, wait for the contact to message the line first, or sign in through the device flow to lift the allowance. On SMS: contact_opted_out (the contact texted STOP; nothing more goes to them until they text START), consent_required (a start to someone who never texted your numbers: record their consent with consent on the start). In a HIPAA account: hipaa_channel_not_covered (the account's HIPAA setting does not allow the channel; use SMS). Simulated conversations: simulated_contact (a real sender was pointed at a simulated contact; reply in the contact's simulated conversation), not_simulated (a simulated sender or test endpoint was pointed at a real contact), test_mode_only, simulated_conversation_limit. In message.failed: sandbox_contact_left (the contact joined another app on the sandbox sender while the message was queued; have them send your join message again).
• not_found (404): no such object for this app and mode. Check the ID's prefix and that it was made with a key of the same mode (test and live data are separate).
• idempotency_conflict (409): the idempotency key was used for a different request (channel_code body_mismatch: use a new key), or that request is still running (in_progress: wait retry_after seconds and repeat it with the same key), or it already created a secret that is shown only once (secret_not_kept: creating a webhook endpoint, rotating its secret, connecting a WhatsApp number; a secret that was lost must be rotated again, and a WhatsApp number connected again to see its verify token).
• outside_window (409, or in message.failed): the channel will not deliver outside its conversation window. On WhatsApp the 24-hour window is closed: send a template (POST /v0/conversations/{conversation_id}/template, or POST /v0/messages with kind template to start), or wait for the contact to write. On iMessage the contact has not messaged the line (or opted in) yet, so the failure arrives as a message.failed event: wait for the contact to write, then reply in that conversation. iMessage has no 24-hour window: once someone has texted your line, your agent can message them any time. Typing and read receipts answer 409 outside_window directly when the channel's window for them is closed; ignore it and send your reply. On iMessage typing and read receipts work only in a two-way conversation, for 5 minutes after your line's last message to the contact, so send your reply first. On WhatsApp read receipts go at any time. On SMS, channel_code quiet_hours: the contact has not texted in the last hour and it is inside the sender's quiet hours in their time zone; retry after retry_after seconds, or wait for them to text. In message.failed: window_closed (WhatsApp's 24-hour window closed while the message was queued; send a template) and queued_too_long (the message waited in the queue longer than its sender allows, for example while the sender was paused; send it again if it still applies).
• unsupported_content (422): the conversation's channel does not take this kind, field, block or value, and nothing was sent; Flow never converts a message. param names what was refused: kind (the endpoint's kind is not on this channel, such as a carousel on Telegram), a field or block (reply_to on SMS, telegram on WhatsApp, telegram.is_big), or the field whose value is not taken (emoji outside Telegram's reaction emoji, buttons for more than 3 WhatsApp buttons). channel is the conversation's channel and hint says what to send instead over plain HTTP; each endpoint's page lists its channels. In an iMessage group conversation, a reaction, typing or a read receipt answers it with param kind and channel_code group_unsupported: leave it out. Removing a reaction on iMessage (emoji null) when you have none on the message answers it with param emoji and channel_code no_reaction_to_remove: iMessage removes a reaction by naming it. Media to an SMS number without MMS answers it with param media and channel_code no_mms. An edit or unsend of an iMessage message that went by SMS or RCS (its network) answers it with channel_code not_on_sms: send a new message instead. An edit or unsend past the channel's time limit answers it with channel_code edit_window_closed or unsend_window_closed (iMessage: edits within 15 minutes of sending, unsends within 2 minutes; Telegram: unsends within 48 hours), and an iMessage edit of the message that started the conversation with first_message_not_editable; message states the limit and how long ago the message was sent. Send a new message instead. POST /v0/files answers it for a type Flow does not take (programs, web pages, unknown types). A send by file_id of a document a contact sent before Flow malware-scanned documents answers it too: Flow sends only documents it scanned. Flow's template on the shared WhatsApp sandbox sender answers it with param params.body[0] and channel_code template_value_not_taken when your message has a line break or tab, more than four spaces in a row, or makes the template longer than WhatsApp's 1024 characters: write it as one shorter line.
• new_contact_limit (429): the sender has used its budget for starting conversations. Wait retry_after seconds; replies into existing conversations still go.
• sender_throttled (429): abuse signals tripped (the same text to many new contacts, many starts with no reply, blocks), so the sender may not start conversations until retry_after; replies into existing conversations still go. Personalise first messages and start only conversations people expect.
• file_blocked (422): the file failed the malware scan and was not stored. Send a different file. (When the scan cannot run at all, the upload answers a retryable 500 api_error with Retry-After instead.)
• rate_limited (429): either too many requests for this key (the per-key request limit, reported in the RateLimit-* headers) or sends faster than the sender's sending rate (pacing). Wait Retry-After (retry_after) seconds and retry with the same Idempotency-Key. On Flow's shared WhatsApp sandbox sender, channel_code flow_template_limit: your app already sent Flow's template to this contact in the last 24 hours; wait for them to reply, or send it after retry_after seconds.
• channel_error (502, or in message.failed): the channel refused or failed the message, or timed out; channel_code carries its own code. Read message, change what the channel objected to, and send again. From typing and read receipts, which call the channel at once, it is safe to ignore. SMS codes are Flow's, the same whichever carrier network carries the message: carrier_filtered (a carrier's spam filter blocked it: make it read like a person's message, no shortened links), unreachable, invalid_number, landline, registration_required (the number's 10DLC or toll-free registration is not approved yet), carrier_error, and provider_not_configured (the SMS sender is not fully set up on Flow's side, so nothing was sent; contact the Flow team). Flow's own codes on every channel: channel_timeout_unknown_outcome (in message.failed: the channel did not answer after the message was sent, and the resends its policy allows did not settle it, so the message may have arrived or not; check with the contact before sending it again) and unknown_outcome (from typing and read receipts: the call timed out after it was sent).
• not_implemented (501): this endpoint or channel is not live yet during the beta. Use a channel that is live (Telegram, iMessage), or check the changelog.
• api_error (500, 503): something went wrong on Flow's side. Retry with the same idempotency key after retry_after seconds, and quote request_id if it persists.

Available options: invalid_request, authentication, permission, not_found, idempotency_conflict, outside_window, unsupported_content, new_contact_limit, sender_throttled, file_blocked, rate_limited, channel_error, not_implemented, api_error

message string required

A sentence for a developer saying what went wrong. Do not parse it; switch on type.

hint string required

One sentence saying what to change to make the request succeed, specific to this case, for example "Send a template instead: POST /v0/conversations/{conversation_id}/template." For unsupported_content it says what to send instead over plain HTTP. Written for developers and coding agents alike. Do not parse it; it may be reworded at any time.

doc_url string<uri> required

The documentation page for this error's type, https://api.flow.engineer/docs/errors/<type>. It says what the error means, why it happens and how to fix it, with code.

param string

The request parameter the error is about, as a dotted path (kind, telegram.is_big, buttons, cards[1].header.type, limit).

retry_after integer

Seconds to wait before retrying, for errors that clear by themselves.

Range: 0 to any

channel enum<string>

The conversation's channel, on errors about what it takes (unsupported_content) and its windows (outside_window).

Available options: telegram, whatsapp, imessage, sms

conversation string

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

sender string

A sender ID, snd_ and a ULID.

Pattern: ^snd_[0-9A-HJKMNP-TV-Z]{26}$

channel_code string

For channel_error, the channel's own error code, as given by the channel. For some other errors, Flow's own code naming the case, for example sandbox_allowance_used (permission: the sandbox allowance is used up), sandbox_contact_limit (permission: the allowance has no room for another contact), sandbox_channel_not_included (permission: the allowance does not cover this sandbox channel), sign_in_required (permission: an app made without an account cannot do this) or sandbox_key_expired (authentication: a key from POST /v0/sandbox/keys passed its expires_at; permission, for a send that carries no key, such as a reply in a webhook answer, from such an app). For idempotency_conflict, always one of body_mismatch (the key was used for a different request), in_progress (the first request is still running; retry_after says when to repeat it) or secret_not_kept (its answer carried a secret shown only once). SMS: contact_opted_out and consent_required (permission), quiet_hours (outside_window, with retry_after), and carrier_filtered, unreachable, invalid_number, landline, registration_required, carrier_error and provider_not_configured (channel_error). HIPAA accounts: hipaa_channel_not_covered (permission). Connecting your own WhatsApp number (POST /v0/senders): whatsapp_token_malformed, whatsapp_token_rejected, whatsapp_app_secret_malformed and whatsapp_number_not_in_account (invalid_request), and whatsapp_number_taken, whatsapp_account_taken and whatsapp_number_managed (permission). Simulated conversations (permission): test_mode_only, not_simulated, simulated_contact and simulated_conversation_limit. For a message that failed after it was queued (message.failed): sandbox_contact_left (permission), window_closed and queued_too_long (outside_window), and channel_timeout_unknown_outcome (channel_error: the channel never confirmed the send, so it may or may not have arrived). iMessage (permission): imessage_not_granted (the account has no access to Flow's shared line: sign in at flow.engineer to start the free trial). Paid plans (permission): plan_people_limit (a send to a person the account's plan holds: the plan had no room for new people on that channel when they wrote; see Account.people, and GET /v0/app's plans for the bigger plan). plan_ended (authentication for a live key, permission for a live send: the account's paid plan ended, so its live keys and sends are paused until the workspace owner chooses a plan again; test keys keep working). imessage_only (retired 27 Oct 2026; no longer sent: shared lines fall back to SMS/RCS). iMessage (unsupported_content): group_unsupported (a reaction, typing or a read receipt in a group conversation; param kind) and not_on_sms (an edit or unsend of a message that went by SMS or RCS; param kind) and line_contact_card_dedicated_only (imessage.line_contact_card on a shared line; param imessage.line_contact_card). SMS (unsupported_content): no_mms (media to a number without MMS; param media). Edits and unsends (unsupported_content): edit_window_closed and unsend_window_closed (the message is older than the channel allows for the change) and first_message_not_editable (iMessage: the message that started the conversation). From typing and read receipts, unknown_outcome (channel_error: the call timed out after it was sent).

request_id string

Flow's ID for this request. Quote it when asking for help.

429 application/json

Too many requests (rate_limited): either this key's request limit (see the RateLimit-* headers) or the sender's sending rate (pacing) was exceeded; retry after Retry-After seconds (also error.retry_after) with the same Idempotency-Key. Or the sender has used its budget for starting conversations (new_contact_limit), or the sender is throttled after abuse signals (sender_throttled); wait retry_after seconds.

error ErrorBody required

The details of an error.

Show child attributes

type enum<string> required

What went wrong. A closed list: new types arrive only with a new API version. Each type has a page at https://api.flow.engineer/docs/errors/<type>, given in the error's doc_url; the error's hint says what to change for the case.

• invalid_request (400, or 413 for a request body over the size limit): the request is malformed or a parameter is invalid. Fix the parameter named in param; the hint says what it must look like. Every endpoint answers it for a Flow-Version header that is not a version this API serves.
• authentication (401): the API key is missing, malformed, unknown, revoked or expired. An Authorization: Bearer header with nothing after it usually means the environment variable holding the key was empty when the header was built (for an MCP client, when the server was added): the hint says so. Send Authorization: Bearer fk_test_... or fk_live_... with a current key; with no key at all, get a test key with POST /v0/sandbox/keys. A sandbox key past its expires_at has channel_code sandbox_key_expired: sign in to claim the app, or get a new key.
• permission (403): the key may not do this, for example a test key using a live sender, a sandbox contact who joined another app, a new conversation from an iMessage line that may only reply, or a send past the app's sandbox allowance (channel_code sandbox_allowance_used, sandbox_contact_limit or sandbox_channel_not_included). Use the key of the right mode, have the contact send your join message, wait for the contact to message the line first, or sign in through the device flow to lift the allowance. On SMS: contact_opted_out (the contact texted STOP; nothing more goes to them until they text START), consent_required (a start to someone who never texted your numbers: record their consent with consent on the start). In a HIPAA account: hipaa_channel_not_covered (the account's HIPAA setting does not allow the channel; use SMS). Simulated conversations: simulated_contact (a real sender was pointed at a simulated contact; reply in the contact's simulated conversation), not_simulated (a simulated sender or test endpoint was pointed at a real contact), test_mode_only, simulated_conversation_limit. In message.failed: sandbox_contact_left (the contact joined another app on the sandbox sender while the message was queued; have them send your join message again).
• not_found (404): no such object for this app and mode. Check the ID's prefix and that it was made with a key of the same mode (test and live data are separate).
• idempotency_conflict (409): the idempotency key was used for a different request (channel_code body_mismatch: use a new key), or that request is still running (in_progress: wait retry_after seconds and repeat it with the same key), or it already created a secret that is shown only once (secret_not_kept: creating a webhook endpoint, rotating its secret, connecting a WhatsApp number; a secret that was lost must be rotated again, and a WhatsApp number connected again to see its verify token).
• outside_window (409, or in message.failed): the channel will not deliver outside its conversation window. On WhatsApp the 24-hour window is closed: send a template (POST /v0/conversations/{conversation_id}/template, or POST /v0/messages with kind template to start), or wait for the contact to write. On iMessage the contact has not messaged the line (or opted in) yet, so the failure arrives as a message.failed event: wait for the contact to write, then reply in that conversation. iMessage has no 24-hour window: once someone has texted your line, your agent can message them any time. Typing and read receipts answer 409 outside_window directly when the channel's window for them is closed; ignore it and send your reply. On iMessage typing and read receipts work only in a two-way conversation, for 5 minutes after your line's last message to the contact, so send your reply first. On WhatsApp read receipts go at any time. On SMS, channel_code quiet_hours: the contact has not texted in the last hour and it is inside the sender's quiet hours in their time zone; retry after retry_after seconds, or wait for them to text. In message.failed: window_closed (WhatsApp's 24-hour window closed while the message was queued; send a template) and queued_too_long (the message waited in the queue longer than its sender allows, for example while the sender was paused; send it again if it still applies).
• unsupported_content (422): the conversation's channel does not take this kind, field, block or value, and nothing was sent; Flow never converts a message. param names what was refused: kind (the endpoint's kind is not on this channel, such as a carousel on Telegram), a field or block (reply_to on SMS, telegram on WhatsApp, telegram.is_big), or the field whose value is not taken (emoji outside Telegram's reaction emoji, buttons for more than 3 WhatsApp buttons). channel is the conversation's channel and hint says what to send instead over plain HTTP; each endpoint's page lists its channels. In an iMessage group conversation, a reaction, typing or a read receipt answers it with param kind and channel_code group_unsupported: leave it out. Removing a reaction on iMessage (emoji null) when you have none on the message answers it with param emoji and channel_code no_reaction_to_remove: iMessage removes a reaction by naming it. Media to an SMS number without MMS answers it with param media and channel_code no_mms. An edit or unsend of an iMessage message that went by SMS or RCS (its network) answers it with channel_code not_on_sms: send a new message instead. An edit or unsend past the channel's time limit answers it with channel_code edit_window_closed or unsend_window_closed (iMessage: edits within 15 minutes of sending, unsends within 2 minutes; Telegram: unsends within 48 hours), and an iMessage edit of the message that started the conversation with first_message_not_editable; message states the limit and how long ago the message was sent. Send a new message instead. POST /v0/files answers it for a type Flow does not take (programs, web pages, unknown types). A send by file_id of a document a contact sent before Flow malware-scanned documents answers it too: Flow sends only documents it scanned. Flow's template on the shared WhatsApp sandbox sender answers it with param params.body[0] and channel_code template_value_not_taken when your message has a line break or tab, more than four spaces in a row, or makes the template longer than WhatsApp's 1024 characters: write it as one shorter line.
• new_contact_limit (429): the sender has used its budget for starting conversations. Wait retry_after seconds; replies into existing conversations still go.
• sender_throttled (429): abuse signals tripped (the same text to many new contacts, many starts with no reply, blocks), so the sender may not start conversations until retry_after; replies into existing conversations still go. Personalise first messages and start only conversations people expect.
• file_blocked (422): the file failed the malware scan and was not stored. Send a different file. (When the scan cannot run at all, the upload answers a retryable 500 api_error with Retry-After instead.)
• rate_limited (429): either too many requests for this key (the per-key request limit, reported in the RateLimit-* headers) or sends faster than the sender's sending rate (pacing). Wait Retry-After (retry_after) seconds and retry with the same Idempotency-Key. On Flow's shared WhatsApp sandbox sender, channel_code flow_template_limit: your app already sent Flow's template to this contact in the last 24 hours; wait for them to reply, or send it after retry_after seconds.
• channel_error (502, or in message.failed): the channel refused or failed the message, or timed out; channel_code carries its own code. Read message, change what the channel objected to, and send again. From typing and read receipts, which call the channel at once, it is safe to ignore. SMS codes are Flow's, the same whichever carrier network carries the message: carrier_filtered (a carrier's spam filter blocked it: make it read like a person's message, no shortened links), unreachable, invalid_number, landline, registration_required (the number's 10DLC or toll-free registration is not approved yet), carrier_error, and provider_not_configured (the SMS sender is not fully set up on Flow's side, so nothing was sent; contact the Flow team). Flow's own codes on every channel: channel_timeout_unknown_outcome (in message.failed: the channel did not answer after the message was sent, and the resends its policy allows did not settle it, so the message may have arrived or not; check with the contact before sending it again) and unknown_outcome (from typing and read receipts: the call timed out after it was sent).
• not_implemented (501): this endpoint or channel is not live yet during the beta. Use a channel that is live (Telegram, iMessage), or check the changelog.
• api_error (500, 503): something went wrong on Flow's side. Retry with the same idempotency key after retry_after seconds, and quote request_id if it persists.

Available options: invalid_request, authentication, permission, not_found, idempotency_conflict, outside_window, unsupported_content, new_contact_limit, sender_throttled, file_blocked, rate_limited, channel_error, not_implemented, api_error

message string required

A sentence for a developer saying what went wrong. Do not parse it; switch on type.

hint string required

One sentence saying what to change to make the request succeed, specific to this case, for example "Send a template instead: POST /v0/conversations/{conversation_id}/template." For unsupported_content it says what to send instead over plain HTTP. Written for developers and coding agents alike. Do not parse it; it may be reworded at any time.

doc_url string<uri> required

The documentation page for this error's type, https://api.flow.engineer/docs/errors/<type>. It says what the error means, why it happens and how to fix it, with code.

param string

The request parameter the error is about, as a dotted path (kind, telegram.is_big, buttons, cards[1].header.type, limit).

retry_after integer

Seconds to wait before retrying, for errors that clear by themselves.

Range: 0 to any

channel enum<string>

The conversation's channel, on errors about what it takes (unsupported_content) and its windows (outside_window).

Available options: telegram, whatsapp, imessage, sms

conversation string

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

sender string

A sender ID, snd_ and a ULID.

Pattern: ^snd_[0-9A-HJKMNP-TV-Z]{26}$

channel_code string

For channel_error, the channel's own error code, as given by the channel. For some other errors, Flow's own code naming the case, for example sandbox_allowance_used (permission: the sandbox allowance is used up), sandbox_contact_limit (permission: the allowance has no room for another contact), sandbox_channel_not_included (permission: the allowance does not cover this sandbox channel), sign_in_required (permission: an app made without an account cannot do this) or sandbox_key_expired (authentication: a key from POST /v0/sandbox/keys passed its expires_at; permission, for a send that carries no key, such as a reply in a webhook answer, from such an app). For idempotency_conflict, always one of body_mismatch (the key was used for a different request), in_progress (the first request is still running; retry_after says when to repeat it) or secret_not_kept (its answer carried a secret shown only once). SMS: contact_opted_out and consent_required (permission), quiet_hours (outside_window, with retry_after), and carrier_filtered, unreachable, invalid_number, landline, registration_required, carrier_error and provider_not_configured (channel_error). HIPAA accounts: hipaa_channel_not_covered (permission). Connecting your own WhatsApp number (POST /v0/senders): whatsapp_token_malformed, whatsapp_token_rejected, whatsapp_app_secret_malformed and whatsapp_number_not_in_account (invalid_request), and whatsapp_number_taken, whatsapp_account_taken and whatsapp_number_managed (permission). Simulated conversations (permission): test_mode_only, not_simulated, simulated_contact and simulated_conversation_limit. For a message that failed after it was queued (message.failed): sandbox_contact_left (permission), window_closed and queued_too_long (outside_window), and channel_timeout_unknown_outcome (channel_error: the channel never confirmed the send, so it may or may not have arrived). iMessage (permission): imessage_not_granted (the account has no access to Flow's shared line: sign in at flow.engineer to start the free trial). Paid plans (permission): plan_people_limit (a send to a person the account's plan holds: the plan had no room for new people on that channel when they wrote; see Account.people, and GET /v0/app's plans for the bigger plan). plan_ended (authentication for a live key, permission for a live send: the account's paid plan ended, so its live keys and sends are paused until the workspace owner chooses a plan again; test keys keep working). imessage_only (retired 27 Oct 2026; no longer sent: shared lines fall back to SMS/RCS). iMessage (unsupported_content): group_unsupported (a reaction, typing or a read receipt in a group conversation; param kind) and not_on_sms (an edit or unsend of a message that went by SMS or RCS; param kind) and line_contact_card_dedicated_only (imessage.line_contact_card on a shared line; param imessage.line_contact_card). SMS (unsupported_content): no_mms (media to a number without MMS; param media). Edits and unsends (unsupported_content): edit_window_closed and unsend_window_closed (the message is older than the channel allows for the change) and first_message_not_editable (iMessage: the message that started the conversation). From typing and read receipts, unknown_outcome (channel_error: the call timed out after it was sent).

request_id string

Flow's ID for this request. Quote it when asking for help.

default application/json

An error. error.type says which (see ErrorType).

error ErrorBody required

The details of an error.

Show child attributes

type enum<string> required

What went wrong. A closed list: new types arrive only with a new API version. Each type has a page at https://api.flow.engineer/docs/errors/<type>, given in the error's doc_url; the error's hint says what to change for the case.

• invalid_request (400, or 413 for a request body over the size limit): the request is malformed or a parameter is invalid. Fix the parameter named in param; the hint says what it must look like. Every endpoint answers it for a Flow-Version header that is not a version this API serves.
• authentication (401): the API key is missing, malformed, unknown, revoked or expired. An Authorization: Bearer header with nothing after it usually means the environment variable holding the key was empty when the header was built (for an MCP client, when the server was added): the hint says so. Send Authorization: Bearer fk_test_... or fk_live_... with a current key; with no key at all, get a test key with POST /v0/sandbox/keys. A sandbox key past its expires_at has channel_code sandbox_key_expired: sign in to claim the app, or get a new key.
• permission (403): the key may not do this, for example a test key using a live sender, a sandbox contact who joined another app, a new conversation from an iMessage line that may only reply, or a send past the app's sandbox allowance (channel_code sandbox_allowance_used, sandbox_contact_limit or sandbox_channel_not_included). Use the key of the right mode, have the contact send your join message, wait for the contact to message the line first, or sign in through the device flow to lift the allowance. On SMS: contact_opted_out (the contact texted STOP; nothing more goes to them until they text START), consent_required (a start to someone who never texted your numbers: record their consent with consent on the start). In a HIPAA account: hipaa_channel_not_covered (the account's HIPAA setting does not allow the channel; use SMS). Simulated conversations: simulated_contact (a real sender was pointed at a simulated contact; reply in the contact's simulated conversation), not_simulated (a simulated sender or test endpoint was pointed at a real contact), test_mode_only, simulated_conversation_limit. In message.failed: sandbox_contact_left (the contact joined another app on the sandbox sender while the message was queued; have them send your join message again).
• not_found (404): no such object for this app and mode. Check the ID's prefix and that it was made with a key of the same mode (test and live data are separate).
• idempotency_conflict (409): the idempotency key was used for a different request (channel_code body_mismatch: use a new key), or that request is still running (in_progress: wait retry_after seconds and repeat it with the same key), or it already created a secret that is shown only once (secret_not_kept: creating a webhook endpoint, rotating its secret, connecting a WhatsApp number; a secret that was lost must be rotated again, and a WhatsApp number connected again to see its verify token).
• outside_window (409, or in message.failed): the channel will not deliver outside its conversation window. On WhatsApp the 24-hour window is closed: send a template (POST /v0/conversations/{conversation_id}/template, or POST /v0/messages with kind template to start), or wait for the contact to write. On iMessage the contact has not messaged the line (or opted in) yet, so the failure arrives as a message.failed event: wait for the contact to write, then reply in that conversation. iMessage has no 24-hour window: once someone has texted your line, your agent can message them any time. Typing and read receipts answer 409 outside_window directly when the channel's window for them is closed; ignore it and send your reply. On iMessage typing and read receipts work only in a two-way conversation, for 5 minutes after your line's last message to the contact, so send your reply first. On WhatsApp read receipts go at any time. On SMS, channel_code quiet_hours: the contact has not texted in the last hour and it is inside the sender's quiet hours in their time zone; retry after retry_after seconds, or wait for them to text. In message.failed: window_closed (WhatsApp's 24-hour window closed while the message was queued; send a template) and queued_too_long (the message waited in the queue longer than its sender allows, for example while the sender was paused; send it again if it still applies).
• unsupported_content (422): the conversation's channel does not take this kind, field, block or value, and nothing was sent; Flow never converts a message. param names what was refused: kind (the endpoint's kind is not on this channel, such as a carousel on Telegram), a field or block (reply_to on SMS, telegram on WhatsApp, telegram.is_big), or the field whose value is not taken (emoji outside Telegram's reaction emoji, buttons for more than 3 WhatsApp buttons). channel is the conversation's channel and hint says what to send instead over plain HTTP; each endpoint's page lists its channels. In an iMessage group conversation, a reaction, typing or a read receipt answers it with param kind and channel_code group_unsupported: leave it out. Removing a reaction on iMessage (emoji null) when you have none on the message answers it with param emoji and channel_code no_reaction_to_remove: iMessage removes a reaction by naming it. Media to an SMS number without MMS answers it with param media and channel_code no_mms. An edit or unsend of an iMessage message that went by SMS or RCS (its network) answers it with channel_code not_on_sms: send a new message instead. An edit or unsend past the channel's time limit answers it with channel_code edit_window_closed or unsend_window_closed (iMessage: edits within 15 minutes of sending, unsends within 2 minutes; Telegram: unsends within 48 hours), and an iMessage edit of the message that started the conversation with first_message_not_editable; message states the limit and how long ago the message was sent. Send a new message instead. POST /v0/files answers it for a type Flow does not take (programs, web pages, unknown types). A send by file_id of a document a contact sent before Flow malware-scanned documents answers it too: Flow sends only documents it scanned. Flow's template on the shared WhatsApp sandbox sender answers it with param params.body[0] and channel_code template_value_not_taken when your message has a line break or tab, more than four spaces in a row, or makes the template longer than WhatsApp's 1024 characters: write it as one shorter line.
• new_contact_limit (429): the sender has used its budget for starting conversations. Wait retry_after seconds; replies into existing conversations still go.
• sender_throttled (429): abuse signals tripped (the same text to many new contacts, many starts with no reply, blocks), so the sender may not start conversations until retry_after; replies into existing conversations still go. Personalise first messages and start only conversations people expect.
• file_blocked (422): the file failed the malware scan and was not stored. Send a different file. (When the scan cannot run at all, the upload answers a retryable 500 api_error with Retry-After instead.)
• rate_limited (429): either too many requests for this key (the per-key request limit, reported in the RateLimit-* headers) or sends faster than the sender's sending rate (pacing). Wait Retry-After (retry_after) seconds and retry with the same Idempotency-Key. On Flow's shared WhatsApp sandbox sender, channel_code flow_template_limit: your app already sent Flow's template to this contact in the last 24 hours; wait for them to reply, or send it after retry_after seconds.
• channel_error (502, or in message.failed): the channel refused or failed the message, or timed out; channel_code carries its own code. Read message, change what the channel objected to, and send again. From typing and read receipts, which call the channel at once, it is safe to ignore. SMS codes are Flow's, the same whichever carrier network carries the message: carrier_filtered (a carrier's spam filter blocked it: make it read like a person's message, no shortened links), unreachable, invalid_number, landline, registration_required (the number's 10DLC or toll-free registration is not approved yet), carrier_error, and provider_not_configured (the SMS sender is not fully set up on Flow's side, so nothing was sent; contact the Flow team). Flow's own codes on every channel: channel_timeout_unknown_outcome (in message.failed: the channel did not answer after the message was sent, and the resends its policy allows did not settle it, so the message may have arrived or not; check with the contact before sending it again) and unknown_outcome (from typing and read receipts: the call timed out after it was sent).
• not_implemented (501): this endpoint or channel is not live yet during the beta. Use a channel that is live (Telegram, iMessage), or check the changelog.
• api_error (500, 503): something went wrong on Flow's side. Retry with the same idempotency key after retry_after seconds, and quote request_id if it persists.

Available options: invalid_request, authentication, permission, not_found, idempotency_conflict, outside_window, unsupported_content, new_contact_limit, sender_throttled, file_blocked, rate_limited, channel_error, not_implemented, api_error

message string required

A sentence for a developer saying what went wrong. Do not parse it; switch on type.

hint string required

One sentence saying what to change to make the request succeed, specific to this case, for example "Send a template instead: POST /v0/conversations/{conversation_id}/template." For unsupported_content it says what to send instead over plain HTTP. Written for developers and coding agents alike. Do not parse it; it may be reworded at any time.

doc_url string<uri> required

The documentation page for this error's type, https://api.flow.engineer/docs/errors/<type>. It says what the error means, why it happens and how to fix it, with code.

param string

The request parameter the error is about, as a dotted path (kind, telegram.is_big, buttons, cards[1].header.type, limit).

retry_after integer

Seconds to wait before retrying, for errors that clear by themselves.

Range: 0 to any

channel enum<string>

The conversation's channel, on errors about what it takes (unsupported_content) and its windows (outside_window).

Available options: telegram, whatsapp, imessage, sms

conversation string

A conversation ID, conv_ and a ULID.

Pattern: ^conv_[0-9A-HJKMNP-TV-Z]{26}$

sender string

A sender ID, snd_ and a ULID.

Pattern: ^snd_[0-9A-HJKMNP-TV-Z]{26}$

channel_code string

For channel_error, the channel's own error code, as given by the channel. For some other errors, Flow's own code naming the case, for example sandbox_allowance_used (permission: the sandbox allowance is used up), sandbox_contact_limit (permission: the allowance has no room for another contact), sandbox_channel_not_included (permission: the allowance does not cover this sandbox channel), sign_in_required (permission: an app made without an account cannot do this) or sandbox_key_expired (authentication: a key from POST /v0/sandbox/keys passed its expires_at; permission, for a send that carries no key, such as a reply in a webhook answer, from such an app). For idempotency_conflict, always one of body_mismatch (the key was used for a different request), in_progress (the first request is still running; retry_after says when to repeat it) or secret_not_kept (its answer carried a secret shown only once). SMS: contact_opted_out and consent_required (permission), quiet_hours (outside_window, with retry_after), and carrier_filtered, unreachable, invalid_number, landline, registration_required, carrier_error and provider_not_configured (channel_error). HIPAA accounts: hipaa_channel_not_covered (permission). Connecting your own WhatsApp number (POST /v0/senders): whatsapp_token_malformed, whatsapp_token_rejected, whatsapp_app_secret_malformed and whatsapp_number_not_in_account (invalid_request), and whatsapp_number_taken, whatsapp_account_taken and whatsapp_number_managed (permission). Simulated conversations (permission): test_mode_only, not_simulated, simulated_contact and simulated_conversation_limit. For a message that failed after it was queued (message.failed): sandbox_contact_left (permission), window_closed and queued_too_long (outside_window), and channel_timeout_unknown_outcome (channel_error: the channel never confirmed the send, so it may or may not have arrived). iMessage (permission): imessage_not_granted (the account has no access to Flow's shared line: sign in at flow.engineer to start the free trial). Paid plans (permission): plan_people_limit (a send to a person the account's plan holds: the plan had no room for new people on that channel when they wrote; see Account.people, and GET /v0/app's plans for the bigger plan). plan_ended (authentication for a live key, permission for a live send: the account's paid plan ended, so its live keys and sends are paused until the workspace owner chooses a plan again; test keys keep working). imessage_only (retired 27 Oct 2026; no longer sent: shared lines fall back to SMS/RCS). iMessage (unsupported_content): group_unsupported (a reaction, typing or a read receipt in a group conversation; param kind) and not_on_sms (an edit or unsend of a message that went by SMS or RCS; param kind) and line_contact_card_dedicated_only (imessage.line_contact_card on a shared line; param imessage.line_contact_card). SMS (unsupported_content): no_mms (media to a number without MMS; param media). Edits and unsends (unsupported_content): edit_window_closed and unsend_window_closed (the message is older than the channel allows for the change) and first_message_not_editable (iMessage: the message that started the conversation). From typing and read receipts, unknown_outcome (channel_error: the call timed out after it was sent).

request_id string

Flow's ID for this request. Quote it when asking for help.

cURL

GET /v0/app

curl --request GET \
  --url https://api.flow.engineer/v0/app \
  --header 'Authorization: Bearer <token>'

JavaScript

GET /v0/app

const response = await fetch("https://api.flow.engineer/v0/app", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <token>"
  }
});

console.log(await response.json());

Python

GET /v0/app

import requests

response = requests.get(
    "https://api.flow.engineer/v0/app",
    headers={
        "Authorization": "Bearer <token>"
    },
)

print(response.json())

Go

GET /v0/app

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://api.flow.engineer/v0/app", nil)
  req.Header.Add("Authorization", "Bearer <token>")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}

Response examples

200

{
  "account": {
    "id": "acct_01JB8YZ3N2Q4R6T8V0X2Z4B6D8",
    "name": "<string>",
    "plan": "free",
    "people": {
      "per": "channel",
      "channels": [
        {
          "channel": "telegram",
          "pool": "shared",
          "limits": [
            {
              "window": "total",
              "limit": 0,
              "used": 0,
              "resets_at": "2026-11-01T12:00:00Z"
            }
          ],
          "held": 0
        }
      ]
    },
    "hipaa": true,
    "created_at": "2026-11-01T12:00:00Z"
  },
  "app": {
    "id": "app_01JB8Z0A1C3E5G7J9K1M3P5R7T",
    "account": "acct_01JB8YZ3N2Q4R6T8V0X2Z4B6D8",
    "name": "<string>",
    "api_version": "<string>",
    "settings": {
      "transcription": true,
      "auto_read": true
    },
    "sandbox_join_code": "brave-otter-40718263",
    "created_at": "2026-11-01T12:00:00Z"
  },
  "api_key": {
    "id": "key_01JB8Z1B2D4F6H8K0M2P4R6T8W",
    "mode": "test",
    "last4": "<string>",
    "created_at": "2026-11-01T12:00:00Z",
    "expires_at": "2026-11-01T12:00:00Z"
  },
  "livemode": true,
  "allowance": {
    "tier": "anonymous",
    "scope": "app",
    "channels": [
      "telegram"
    ],
    "contacts": {
      "limit": 0,
      "used": 0
    },
    "messages_per_contact": 0,
    "messages": {
      "limit": 0,
      "used": 0,
      "remaining": 0
    },
    "expires_at": "2026-11-01T12:00:00Z",
    "upgrade": "<string>"
  },
  "plans": {
    "current": "free",
    "next": "shared",
    "upgrade_url": "https://flow.engineer/dashboard/plans?plan=shared",
    "offers": [
      {
        "plan": "shared",
        "name": "Shared",
        "usd_per_month": 25,
        "people": [
          {
            "window": "day",
            "limit": 1
          }
        ],
        "includes": "<string>",
        "url": "https://flow.engineer/dashboard/plans?plan=shared"
      }
    ],
    "add_ons": [
      {
        "add_on": "outbound",
        "name": "Outbound",
        "usd_per_month": 40,
        "plans": [
          "<string>"
        ],
        "includes": "<string>",
        "url": "https://flow.engineer/dashboard/plans?plan=dedicated"
      }
    ]
  }
}

400

{
  "error": {
    "type": "invalid_request",
    "message": "limit must be between 1 and 100.",
    "hint": "Pass limit between 1 and 100 (default 20), and page with after or before.",
    "doc_url": "https://api.flow.engineer/docs/errors/invalid_request",
    "param": "limit"
  }
}

401

{
  "error": {
    "type": "authentication",
    "message": "No valid API key was given.",
    "hint": "Send the header Authorization: Bearer fk_test_... (or fk_live_...); no key yet? Get a test key with curl -X POST https://api.flow.engineer/v0/sandbox/keys",
    "doc_url": "https://api.flow.engineer/docs/errors/authentication"
  }
}

429

{
  "error": {
    "type": "new_contact_limit",
    "message": "This sender has started its 15 new conversations for today.",
    "hint": "Retry after 3600 seconds; replies into existing conversations still go.",
    "doc_url": "https://api.flow.engineer/docs/errors/new_contact_limit",
    "retry_after": 3600,
    "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T"
  }
}

default

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "hint": "Send a template instead: POST /v0/conversations/{conversation_id}/template.",
    "doc_url": "https://api.flow.engineer/docs/errors/outside_window",
    "param": "<string>",
    "retry_after": 0,
    "channel": "telegram",
    "conversation": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
    "sender": "snd_01JB8Z4Q3V6W0R2N7C5H1M9K4T",
    "channel_code": "<string>",
    "request_id": "<string>"
  }
}