> ## Documentation Index > Fetch the complete documentation index at: https://docs.botshield.ai/llms.txt > Use this file to discover all available pages before exploring further. # Place a BotShield Action > Place a BotShield Action from your server — the same rules as the Console: live once placed, `actKey` unique per environment. Then send `act` (e.g. `watch` or `dibs:listing_4417`) on `create-verification-link`; the part before ':' must match `actKey`. ## OpenAPI ````yaml /openapi.json post /gates-api/actions/create openapi: 3.1.0 info: title: BotShield API version: 2.0.0 description: >- The BotShield partner API. **BotShield Gate** — ask whether a live human is present (Human Gate) or over an age threshold (Age Gate). The person confirms with their passkey in the BotShield app and you receive a signed result. Partners learn *that* a user is human, never *who*. **Agents Ask** — your agent proposes an action, a verified human confirms or denies it, and BotShield signs a Proof of Resolution you can verify offline. **Gates API** — place and run gates and BotShield Actions from your server. **Verified Accounts** — a person links their account on your platform with a passkey; your server reads the status and the registry, and can unlink (revoke) an account with its API key. Every operation answers HTTP 200 with a `data` envelope; handler errors arrive as `data.error`. See the API overview and error reference. In the `botshield-sdk` package (2.2.1) these operations live under `client.census.*`, `client.verification.*`, `client.gates.*`, `client.securedAccounts.*` and `client.actions.*`. contact: name: BotShield Support email: support@botshield.ai url: https://botshield.ai servers: - url: https://api.botshield.ai/operations description: Production security: [] tags: - name: BotShield Gate description: >- Ask whether a present human (Human Gate) or a human over an age threshold (Age Gate) confirmed, and verify the signed result. - name: Gates API description: >- Place, open, extend and close gates, and place BotShield Actions, from your server with an API key that has the `gates:write` scope. - name: Verified Accounts description: >- Read and end the Verified Accounts on your platform from your server with your API key: status, the registry, and revoke (unlink). - name: Agents Ask description: >- Your agent proposes an action; a verified human confirms or denies it in the BotShield app; you receive a signed Proof of Resolution. paths: /gates-api/actions/create: post: tags: - Gates API summary: Place a BotShield Action description: >- Place a BotShield Action from your server — the same rules as the Console: live once placed, `actKey` unique per environment. Then send `act` (e.g. `watch` or `dibs:listing_4417`) on `create-verification-link`; the part before ':' must match `actKey`. operationId: GatesApiActionsCreate requestBody: required: true content: application/json: schema: type: object required: - name - actKey properties: name: type: string minLength: 1 maxLength: 60 description: Shown to the person on their card. example: Watch with passkey actKey: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$ description: >- Lower-case letters, digits, `_` or `-`, up to 40 (input is lower-cased). example: watch whereUrl: type: string format: uri maxLength: 2048 description: Where the action lives on your surface. `https://` only. example: https://example.com/listings example: name: Watch with passkey actKey: watch whereUrl: https://example.com/listings responses: '200': description: >- 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). content: application/json: schema: type: object required: - data properties: data: type: object properties: data: type: object required: - action properties: action: $ref: '#/components/schemas/BotShieldAction' error: $ref: '#/components/schemas/GatesApiError' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalError' security: - GatesKeyAuth: [] components: schemas: BotShieldAction: type: object required: - id - name - act_key - where_url - state - environment - placed_at - turned_off_at description: >- A BotShield Action: one act on your own surface keyed to a passkey. Not a gate — no schedule, no levers — and it always stands on a verified account, so a tap runs the linking ceremony. properties: id: type: string format: uuid name: type: string maxLength: 60 description: Shown to the person on their card. example: Watch with passkey act_key: type: string pattern: ^[a-z0-9][a-z0-9_-]{0,39}$ description: The part of `act` before the first ':' that names this action. example: watch where_url: type: - string - 'null' format: uri description: Where the action lives on your surface (informational). state: type: string enum: - live - 'off' description: '`off` refuses new requests at once (`action_off`).' environment: type: string enum: - development - production placed_at: type: string format: date-time turned_off_at: type: - string - 'null' format: date-time GatesApiError: type: object required: - message - statusCode - code description: >- Gates API handler error. Arrives inside `data.error` with HTTP 200 — check for it before reading the result. properties: message: type: string statusCode: type: integer example: 409 code: type: string example: gate_key_taken InvalidInputError: type: object required: - message - input - errors properties: message: type: string example: Invalid input provided input: type: object additionalProperties: true errors: type: array items: type: object required: - propertyPath - invalidValue - message properties: propertyPath: type: string invalidValue: description: The invalid value message: type: string ErrorResponse: type: object required: - error properties: error: type: object required: - message - statusCode properties: message: type: string statusCode: type: integer responses: BadRequest: description: Invalid input content: application/json: schema: $ref: '#/components/schemas/InvalidInputError' InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: GatesKeyAuth: type: http scheme: bearer description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.