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. Keys are scoped per environment (sandbox or production); pick the one that matches the environment you're targeting.

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.

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.