Flow Completions

Receiving a verification email is only half the job. The email contains a link that must be clicked to activate the account, and that link often leads to a page with a button, a form, or a CAPTCHA. In a manual test, a human clicks through it. In a CI pipeline or an AI agent workflow, the test stalls because there's nothing to operate the browser.

Flow completions bridge this gap. They provide a server-side browser agent that navigates to the URL from a received message, clicks elements, fills forms, submits pages, and captures screenshots as evidence of what happened. Combined with receivers (to capture the email) and TOTP (to handle any 2FA challenge along the way), flow completions let you automate an entire signup-to-verified flow without human interaction.

Start a flow

curl -X POST https://api.bouncehouse.cloud/api/accounts/me/flow-completions \
  -H "Authorization: Bearer bh_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/verify?token=abc123",
    "instructions": "Click the verify button",
    "max_duration_seconds": 60
  }'

Returns {id, url, status, instructions, page_state, evidence_urls, created_at}.

The response includes page_state, which describes what the browser sees on the page: the page title, current URL, visible links, form fields, and buttons. This lets your automation decide what action to take next based on the actual page content, rather than hardcoding selectors that break when the UI changes.

Status values: active, completed, failed, timeout, cancelled

Take actions

Once a flow is active, send browser actions:

curl -X POST https://api.bouncehouse.cloud/api/accounts/me/flow-completions/{id}/actions \
  -H "Authorization: Bearer bh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "click", "selector": "button.verify", "timeout": 5000}'

Each action returns its result and an updated page_state, so you can chain actions based on what changed.

Available actions:

Evidence collection

When a flow completes, fails, or is cancelled, Bounce House automatically captures evidence:

• Final screenshot — image of the page at completion
• HAR recording — full HTTP Archive of every request the browser made during the flow, useful for debugging network issues or verifying that the right requests were sent

Evidence URLs are returned in the evidence_urls field on the flow completion response. On failure, evidence is captured before the browser session is closed, so you can see exactly what the page looked like when things went wrong.

Complete a flow

Mark a flow as successfully completed:

curl -X POST https://api.bouncehouse.cloud/api/accounts/me/flow-completions/{id}/complete \
  -H "Authorization: Bearer bh_your_key"

This captures a final screenshot and HAR recording, closes the browser session, and sets the status to completed.

Cancel a flow

Cancel an active flow and release the browser session:

curl -X DELETE https://api.bouncehouse.cloud/api/accounts/me/flow-completions/{id} \
  -H "Authorization: Bearer bh_your_key"

Captures evidence before closing.

Get flow status

curl https://api.bouncehouse.cloud/api/accounts/me/flow-completions/{id} \
  -H "Authorization: Bearer bh_your_key"

List flows

curl "https://api.bouncehouse.cloud/api/accounts/me/flow-completions?status=active&limit=50" \
  -H "Authorization: Bearer bh_your_key"

Filter by status (active, completed, failed, timeout, cancelled).

List actions

curl https://api.bouncehouse.cloud/api/accounts/me/flow-completions/{id}/actions \
  -H "Authorization: Bearer bh_your_key"

Returns the full history of actions taken during the flow, each with its result and any error.

Rate limits and security

• Max concurrent flows: 3 per account
• Max flows per hour: 20 per account
• Max duration per flow: 120 seconds (configurable per-flow, capped by account limit)
• URL allowlist: optionally restrict which URLs flows can navigate to

URLs are validated before the browser session starts. If a URL allowlist is configured, only URLs matching the allowlist are permitted.