Your engagement data, in your own tools

One header, one key

Create a key in Settings → API. The full key is shown once, at creation. We store a SHA-256 hash of it, so if it's lost the only path forward is to revoke it and mint a new one.

# Every request carries the key as a bearer token.
curl https://app.bloomder.io/api/v1/surveys \
  -H "Authorization: Bearer blm_live_YOUR_KEY_HERE"

What a key can and cannot do

• Scoped to the organization that created it. There is no cross-organization key.
• Read-only. The API has no write endpoints at all, so a leaked key cannot alter, delete or send anything.
• Revocable at any time by the account owner, taking effect on the next request.
• Optionally set to expire after a number of days. Left blank, a key does not expire — a silent expiry would break a customer's nightly job months after they set it up.

Cursors, not page numbers

List endpoints return a page of data and a next_cursor. Pass that cursor back to get the next page; null means you've reached the end. Cursors are stable under inserts, which offset-based paging is not — a survey created mid-scan cannot make you skip or repeat a row.

# First page: 50 surveys.
curl "https://app.bloomder.io/api/v1/surveys?limit=50" \
  -H "Authorization: Bearer $BLOOMDER_KEY"

# Response
{
  "data": [ { "id": "clx…", "name": "Q3 Pulse", "status": "ACTIVE", … } ],
  "next_cursor": "clx8f2k…"
}

# Next page.
curl "https://app.bloomder.io/api/v1/surveys?limit=50&cursor=clx8f2k…" \
  -H "Authorization: Bearer $BLOOMDER_KEY"

limit defaults to 25 and is capped at 100. A larger value is clamped, not rejected.

120 requests per minute, per key

The budget is per key rather than per organization or per IP: your integration runs from wherever your infrastructure happens to be, and two keys in one account should not compete for the same allowance.

• X-RateLimit-Limit and X-RateLimit-Window come back on every response, not only on a 429, so a client can pace itself before it gets refused.
• On a 429, Retry-After gives the seconds to wait. Respect it rather than retrying immediately.
• Need more for a bulk backfill? Write to [email protected] and tell us the shape of the job.

Every endpoint, in one table

All paths are relative to https://app.bloomder.io/api/v1. There are no write endpoints.

A complete example

Pull the latest results for every active survey — the shape most BI refreshes take.

#!/usr/bin/env bash
# Requires: curl, jq. Set BLOOMDER_KEY in your environment.
set -euo pipefail
BASE="https://app.bloomder.io/api/v1"
AUTH=(-H "Authorization: Bearer $BLOOMDER_KEY")

curl -s "$BASE/surveys?limit=100" "${AUTH[@]}" \
  | jq -r '.data[] | select(.status == "ACTIVE") | .id' \
  | while read -r id; do
      curl -s "$BASE/surveys/$id/results" "${AUTH[@]}" \
        | jq '{survey: .survey_name, rate: .run.response_rate, suppressed, nps: .nps_score}'
    done