Skip to main content
POST
Place a BotShield Action

Authorizations

Authorization
string
header
required

Your secret server API key (bs_dev_… or bs_production_…) with Gates API access: the gates:write scope, granted in the Console under Settings → Developer Tools → API Keys. Without it every Gates API call answers gates_scope_required. The organization and environment always come from the key. Site keys are refused.

Body

application/json
name
string
required

Shown to the person on their card.

Required string length: 1 - 60
Example:

"Watch with passkey"

actKey
string
required

Lower-case letters, digits, _ or -, up to 40 (input is lower-cased).

Pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$
Example:

"watch"

whereUrl
string<uri>

Where the action lives on your surface. https:// only.

Maximum string length: 2048
Example:

"https://example.com/listings"

Response

The placed action. NOTE: handler errors also arrive here (HTTP 200) as data.error — codes: invalid_key (401 — missing, malformed or inactive key), gates_scope_required (403 — the key lacks Gates API access), org_not_found (404), action_key_taken (409), internal (500).

data
object
required