> ## 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 gate > Place a gate from your server. It is placed as a `draft`; send `activate: true` to make it live in the same call. In Production the Console's checks apply to activation — business verified, a verified domain, the plan's gate allowance — and if they block it the gate is still placed: the call succeeds with `activated: false` and `activation_error`. The policy document is the `preset`'s pre-fill overlaid by `policy`, validated whole (`version` defaults to 3 when neither sends one). A key is never auto-suffixed: a key already placed in this environment is refused with `gate_key_taken`. Nothing is half-placed — if the policy cannot be saved, the gate is removed. ## OpenAPI ````yaml /openapi.json post /gates-api/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/create: post: tags: - Gates API summary: Place a gate description: >- Place a gate from your server. It is placed as a `draft`; send `activate: true` to make it live in the same call. In Production the Console's checks apply to activation — business verified, a verified domain, the plan's gate allowance — and if they block it the gate is still placed: the call succeeds with `activated: false` and `activation_error`. The policy document is the `preset`'s pre-fill overlaid by `policy`, validated whole (`version` defaults to 3 when neither sends one). A key is never auto-suffixed: a key already placed in this environment is refused with `gate_key_taken`. Nothing is half-placed — if the policy cannot be saved, the gate is removed. operationId: GatesApiCreate requestBody: required: true content: application/json: schema: type: object required: - key - name properties: key: type: string pattern: ^[a-z0-9][a-z0-9_-]{0,63}$ description: >- The gate key: lower-case letters, digits, `_` or `-`, up to 64, starting with a letter or digit. What `create-verification-link` sends as `gate`. Unique per environment. example: presale-nyc-1120 name: type: string minLength: 1 maxLength: 120 example: NYC presale message: type: string maxLength: 90 description: The gate's line to people on the arrival card. example: Two tickets per fan. Real fans only. gateType: type: string enum: - human - age default: human ageThreshold: type: integer enum: - 13 - 18 - 21 description: >- Required when `gateType` is `age` (else `age_threshold_required`). preset: type: string enum: - presale - promo - drop - vote - reservation - claim description: >- Pre-fill the policy from a preset; any `policy` fields override it. policy: $ref: '#/components/schemas/GatePolicyDoc' destinationUrl: type: string format: uri maxLength: 2048 description: >- Where the gate sends a person after they pass. `https://` only. Revealed to the person only after their request passes. example: https://example.com/presale/nyc activate: type: boolean default: false description: Make the gate live in the same call. example: key: presale-nyc-1120 name: NYC presale message: Two tickets per fan. preset: presale policy: version: 3 link: required schedule: opensAt: '2026-11-20T17:00:00Z' destinationUrl: https://example.com/presale/nyc activate: true responses: '200': description: >- The placed gate. 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), `age_threshold_required` (400), `invalid_policy` (400), `gate_key_taken` (409), `internal` (500). content: application/json: schema: type: object required: - data properties: data: type: object properties: data: type: object required: - gate - activated properties: gate: $ref: '#/components/schemas/Gate' activated: type: boolean description: Whether the gate is live now. activation_error: allOf: - $ref: '#/components/schemas/GatesApiError' description: >- Present only when `activate: true` was sent and Production activation was blocked: `org_not_verified`, `domain_not_verified` or `gate_limit_reached` (403). The gate stays a draft — call activate once fixed. error: $ref: '#/components/schemas/GatesApiError' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalError' security: - GatesKeyAuth: [] components: schemas: GatePolicyDoc: type: object required: - version additionalProperties: false description: >- A gate's policy document (versioned; validated whole). Unknown fields are refused. When `preset` is also sent on the create call, the preset pre-fills these fields and any field here overrides it. properties: version: type: integer enum: - 1 - 2 - 3 description: Document version. Send 3 (v3 adds `link`). example: 3 preset: type: - string - 'null' enum: - presale - promo - drop - vote - reservation - claim - null description: >- The label for the moment. It only pre-fills attributes; the engine never branches on it. Null/omitted = Custom. link: type: string enum: - required - optional - never description: >- Does a pass link the person to your platform? `required` — you must send `partner_user_ref` with every request and the pass links in the same tap; `optional` — links when a ref is sent, anonymous otherwise; `never` — no link, no ref kept. Always `never` on an Age Gate. Tightens like a limit: required > optional > never. example: optional signedUp: type: boolean description: >- Only people who signed up for this one may pass. Stored now; enforced with sign-ups. schedule: $ref: '#/components/schemas/GateSchedule' asks: type: string enum: - always description: >- A gate always asks — every pass is a fresh confirmation on the person's phone. The field exists only so a document can say so. passesPerPerson: oneOf: - $ref: '#/components/schemas/PassesPerPerson' - type: 'null' description: Null = as often as they like. realDaysAtLeast: type: integer minimum: 0 maximum: 365 description: >- The person's BotShield ID must have proved a person on at least this many distinct days. 0 = anyone. example: 0 example: version: 3 preset: presale link: required passesPerPerson: limit: 2 window: ever realDaysAtLeast: 0 schedule: opensAt: '2026-11-20T17:00:00Z' closesAt: null Gate: type: object required: - key - name - message - status - state - environment - destination_url - policy - placed_at - placed_by_api description: >- A gate as the Gates API returns it — your own facts about the gate, never anything about people. properties: key: type: string pattern: ^[a-z0-9][a-z0-9_-]{0,63}$ description: The gate key — what `create-verification-link` sends as `gate`. example: presale-nyc-1120 name: type: string example: NYC presale message: type: - string - 'null' description: The gate's line to people on the arrival card. status: type: string enum: - draft - active - closed description: >- `draft` until activated; `closed` once closed (a closed gate cannot be reopened). state: type: - string - 'null' enum: - scheduled - open - closed - null description: >- Where an active gate is in its schedule. Null unless `status` is `active`. environment: type: string enum: - development - production description: The key's environment. destination_url: type: - string - 'null' format: uri description: Where the gate sends a person after they pass. policy: type: - object - 'null' description: >- The effective policy (base → org → gate). Null if none could be loaded. required: - preset - gate_type - age_threshold - signed_up - link - passes_per_person - real_days_at_least - schedule - line properties: preset: type: - string - 'null' enum: - presale - promo - drop - vote - reservation - claim - null gate_type: type: string enum: - human - age age_threshold: type: - integer - 'null' enum: - 13 - 18 - 21 - null description: Age Gate only; null on a Human Gate. signed_up: type: boolean link: type: string enum: - required - optional - never passes_per_person: oneOf: - $ref: '#/components/schemas/PassesPerPerson' - type: 'null' description: Null = as often as they like. real_days_at_least: type: integer minimum: 0 maximum: 365 schedule: type: object required: - opensAt - closesAt properties: opensAt: type: - string - 'null' format: date-time closesAt: type: - string - 'null' format: date-time line: type: string description: The human-readable policy readback the Console shows. example: 2 per person · ever placed_at: type: string format: date-time placed_by_api: type: boolean description: true when an API key (not the Console) placed the gate. 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 GateSchedule: type: object additionalProperties: false description: The gate's runtime. `closesAt` must be after `opensAt`. properties: opensAt: type: - string - 'null' format: date-time description: >- When the gate opens (ISO 8601 with offset). Omitted/null = open from placement. example: '2026-11-20T17:00:00Z' closesAt: type: - string - 'null' format: date-time description: When it closes. Omitted/null = runs until closed. example: '2026-11-22T05:00:00Z' PassesPerPerson: type: object required: - limit - window additionalProperties: false description: >- Passes per person on your platform: `limit` per `window` (`30d` = rolling 30 days, `ever` = lifetime). properties: limit: type: integer minimum: 1 maximum: 100 example: 2 window: type: string enum: - day - week - 30d - ever example: ever 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.