Authentication

API Base URL

Unless otherwise specified, all V3 endpoints use https://api.bem.ai as their base URL and live under the /v3/* path prefix.

API Keys

Every request requires an API key, sent as an x-api-key header. Generate keys from Settings → API Keys in the bem dashboard.

curl https://api.bem.ai/v3/workflows \
  -H "x-api-key: $BEM_API_KEY"

The official SDKs and CLI read BEM_API_KEY from the environment by default — see SDKs and CLI.

Environments

Every account is seeded with two environments, production and sandbox, that isolate your data. Each API key belongs to exactly one of them, and the environment is derived from the key — there is no environment header or query parameter on the API. To move work from sandbox to production you swap the key (typically the BEM_API_KEY value); the URLs, bodies, and function names stay the same. The dashboard is a separate surface: it selects an environment via its own cookie-based toggle, independent of your API keys.

Webhook signatures

When a signing secret is active on your account, every webhook delivery includes a bem-signature header in the format t={unix_timestamp},v1={hex_hmac_sha256}. The signature covers {timestamp}.{raw_request_body} and can be verified with HMAC-SHA256 using your secret.

For end-to-end setup (generating the secret, subscribing a function, and verifying deliveries with copy-pasteable code in Node, Python, and Go) see Webhooks. The endpoints for managing the secret itself are under Webhook Signing.

Pagination

V3 list endpoints use cursor-based pagination via two mutually exclusive parameters:

• startingAfter — return the page after the given object ID. Use this to step forward.
• endingBefore — return the page before the given object ID. Use this to step backward.

The cursor is the ID of an object in the previous page (typically the last for forward paging, the first for backward paging). Pass limit (default 50, max 100) to control page size. Conventions match the Stripe API.

# First page
curl "https://api.bem.ai/v3/workflows?limit=50" -H "x-api-key: $BEM_API_KEY"

# Next page (use the last workflow's ID from the previous page)
curl "https://api.bem.ai/v3/workflows?limit=50&startingAfter=wf_abc123" \
  -H "x-api-key: $BEM_API_KEY"

Error responses

Every non-2xx response carries a body with message, an optional code, and optional details. See Errors and status codes for the full breakdown and retry guidance.