Skip to main content
The endpoints under https://api.flowiq.live/v1 (Calling, Webhook deliveries, Subscriptions, Reports) share these rules. Older endpoints (/send-text, /send-template, /contact, …) keep their own, simpler shapes.

Request ids

Every response carries an X-Request-Id header, and every error body repeats it as request_id. Quote it when you write to support: it finds the exact request in FlowIQ’s logs.

Errors

Errors are JSON with a short label, a stable machine-readable code, a sentence for a person, and the request id. Branch on code, never on message.
The 401 for a missing or invalid key comes from the shared key check and carries error and message only. Key permissions (read, send, write) apply to every endpoint, the older ones included. Those answer a call outside the key’s permissions with 403 and error: "Insufficient permission", plus required_scope and key_scopes; see Key permissions.

Rate limits

Limits are per API key: 240 reads a minute and 60 actions a minute (anything that sends, calls or changes settings). Every response says where you stand:

Idempotency keys

Send an Idempotency-Key header (any string up to 255 characters, a UUID is a good choice) on a POST or PATCH and FlowIQ remembers the response for 24 hours per API key. A retry with the same key and the same body gets the same response back, with Idempotent-Replayed: true, without doing the work again: a network glitch can never start a call twice or send two permission requests.
  • The same key with a different body is refused: 422 idempotency_key_reused.
  • A retry while the first request is still running: 409 idempotency_in_progress.
  • 5xx answers are not remembered, so a retry after a FlowIQ-side failure runs again.

Paging

Lists are cursor-paged: pass limit (max 100) and, for the next page, the next_cursor from pagination as ?cursor=. A page with has_more: false is the last one. Cursors are opaque; a cursor you did not get from the API answers 400 invalid_cursor. (The Subscriptions endpoints still use page.)