API Reference

The Bounce House API is a REST API with JSON request and response bodies.

Browse the full interactive API reference for complete endpoint documentation with request/response schemas, or read the overview below.

Base URL

https://api.bouncehouse.cloud

Authentication

All requests require a Bearer token with a bh_ prefix:

curl https://api.bouncehouse.cloud/api/accounts/me/dashboard-summary \
  -H "Authorization: Bearer bh_your_key"

API keys use the bh_ prefix. The full key is only shown once at creation — store it securely. Keys are identified by their first 7 characters (e.g. bh_abc1) and validated via SHA-256 hash.

Create API keys in the dashboard settings or via the API:

curl -X POST https://api.bouncehouse.cloud/api/accounts/me/api-keys \
  -H "Authorization: Bearer bh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"label": "ci-pipeline"}'

Quick start

# 1. Create an account and get an API key
curl -X POST https://api.bouncehouse.cloud/api/accounts \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "..."}'

# Response includes your API key (bh_ prefix, shown only once)

# 2. Create an email receiver
curl -X POST https://api.bouncehouse.cloud/api/accounts/me/receivers \
  -H "Authorization: Bearer bh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"channel": "email", "label": "test", "ttl_seconds": 3600}'

# 3. Wait for a message (long-poll, no polling needed)
curl "https://api.bouncehouse.cloud/api/accounts/me/receivers/{id}/wait?timeout=30" \
  -H "Authorization: Bearer bh_your_key"

# 4. Add a domain for monitoring
curl -X POST https://api.bouncehouse.cloud/api/accounts/me/domains \
  -H "Authorization: Bearer bh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

Rate limits

API requests are rate-limited to 100 requests/minute per API key. Current limits are returned in response headers:

• X-RateLimit-Limit — requests allowed per window
• X-RateLimit-Remaining — requests remaining
• X-RateLimit-Reset — window reset (UTC timestamp)

Exceeding the limit returns 429 with a Retry-After header.

What's in the REST API vs. Data API

After PR #329 the dashboard reads tenant rows directly from Neon's Data API (a PostgREST surface) over the bouncehouse schema, with row-level security scoping every query to the calling tenant. The Bearer-token REST API documented here keeps the surface that needs server-side coordination:

• Account lifecycle and credentials — account create, API-key issue, addresses sign, account update / delete.
• Domains — register / delete, DMARC sources + guidance, live DNS lookup, DNS recommendations apply / dismiss, MX setup & verify, reporting-address (HMAC-signed), live health recompute.
• Receivers — create (HMAC-signs the address), delete (releases SMS pool), and /wait long-poll on Redis pub/sub.
• Sending / DNS / auth providers — create with server-side encryption, fanout-URL admin, domain-link writes, setup acknowledgement.
• Outbound webhooks — POST /event-subscriptions/{id}/test signs and dispatches a synthetic event.
• Deliveries — manual retry (re-queues background dispatch).
• Preferences — registry-merged defaults, per-key blast-radius preview, multi-layer resolver, group + override writes.
• Events / messages — registered-types enum, daily volume, type breakdown, current-month usage, message delete (audit event).
• Alerts — acknowledge / unacknowledge with audit row.
• Suppression — GET /check with classification.
• Webhook ingress — email, provider, auth-provider, SMS, Polar.
• Admin / maintenance / benchmarks — cross-tenant operational surfaces.

Tenant list / detail reads (domains, messages, events, receivers, deliveries, suppression entries, auth-provider configs, sending-provider configs, DNS connections, event subscriptions, DMARC reports + records, health-score history, group + override rows) are served by Data API, not the REST API. Hit https://<project>.data-api.neon.tech/rest/v1/<table> with the short-lived JWT issued by Better Auth instead.

OpenAPI spec

The full OpenAPI specification covers only the REST API surface above:

https://api.bouncehouse.cloud/openapi.json

Errors

All errors return JSON with a detail field:

{ "detail": "Domain not found" }