> ## 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. # Propose an action for human confirmation > Agents Ask a human-presence-gated action for a BotShield user. The user receives the card in the BotShield app (Agents Ask), confirms or denies with a biometric ceremony, and BotShield delivers a signed Proof of Resolution JWT through `GET /agentlink/check-status` and the `agents_ask.resolution.*` webhooks. Identify the user by opaque_id — the pairwise id from the bind ceremony. Authentication: agent key (bs_agent___) in the Authorization header. ## OpenAPI ````yaml /openapi.json post /agentlink/inquire 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 device biometric 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. 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 these operations live under `client.census.*`, `client.verification.*` 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: >- Place a gate and learn whether a present human (Human Gate) or a human over an age threshold (Age Gate) confirmed. - 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: /agentlink/inquire: post: tags: - Agents Ask summary: Propose an action for human confirmation description: >- Agents Ask a human-presence-gated action for a BotShield user. The user receives the card in the BotShield app (Agents Ask), confirms or denies with a biometric ceremony, and BotShield delivers a signed Proof of Resolution JWT through `GET /agentlink/check-status` and the `agents_ask.resolution.*` webhooks. Identify the user by opaque_id — the pairwise id from the bind ceremony. Authentication: agent key (bs_agent___) in the Authorization header. operationId: ActionsPropose requestBody: required: true content: application/json: schema: type: object required: - request_id - action properties: request_id: type: string format: uuid description: >- Agent-supplied UUID for idempotency. Re-proposing with the same request_id returns the existing card_id. opaque_id: type: string minLength: 4 maxLength: 64 description: >- CANONICAL. The pairwise id this agent holds for the human, obtained once via the bind ceremony (agent/bind-session → claim → check-binding). Meaningless to any other agent. Provide exactly one of opaque_id, botshield_user_id, user_email. botshield_user_id: type: string format: uuid description: >- The user's global BotShield id. Prefer opaque_id — this key is identical across agents and can correlate a human between integrations. user_email: type: string format: email deprecated: true description: >- Deprecated — use opaque_id. Email of the BotShield user to receive this proposal. action: type: object required: - summary_title - category properties: summary_title: type: string description: >- Plain-English action description shown on the card (e.g. 'Has an Uber ride ready to book'). summary_detail: type: object description: Primary KPI shown on the card chrome. properties: label: type: string example: TOTAL value: type: string example: $100.90 category: type: string description: >- Must be in agent.allowed_action_categories AND in the partner's approved scopes for this environment. example: travel.book trusted_account_id: type: string format: uuid description: Optional link to the user's trusted account. adaptive_card_payload: type: object description: >- Optional Adaptive Card v1.5 JSON shown when the user expands the card. Allowlist: TextBlock, FactSet, ColumnSet, Container, Table, Image (bundled-asset only). additionalProperties: true ttl_seconds: type: integer minimum: 60 maximum: 86400 default: 600 description: >- How long the user has to respond before the proposal expires (60–86400; default 600). Out-of-range values are rejected with ttl_below_floor / ttl_above_ceiling. responses: '200': description: >- Action proposal queued (or replayed). NOTE: handler errors also arrive here (HTTP 200) as data.error — codes for this operation: 401, 403 (category_not_allowed), 404 (no binding for opaque_id / user not found), 422 (Adaptive Card rejected, see violations), 400 with code ttl_below_floor | ttl_above_ceiling, 500, 502 (user lookup failed). content: application/json: schema: type: object required: - data properties: data: type: object properties: data: type: object required: - status - card_id properties: status: type: string enum: - queued - approved - denied - expired - cancelled description: >- 'queued' on first proposal. On an idempotent replay (same request_id) the card's CURRENT status. card_id: type: string format: uuid ttl_at: type: string format: date-time description: Present on first proposal only. idempotent_replay: type: boolean description: >- true when this request_id was already proposed; no new card was created. error: $ref: '#/components/schemas/ErrorBody' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalError' security: - AgentKeyAuth: [] components: schemas: ErrorBody: type: object required: - message - statusCode description: >- Handler error. Arrives inside data.error with HTTP 200 — check for it before reading the result. properties: message: type: string statusCode: type: integer description: >- The HTTP status the error stands for (401, 403, 404, 409, 422, 500, 502). code: type: string description: Machine code when present, e.g. ttl_below_floor, ttl_above_ceiling. min_ttl_seconds: type: integer max_ttl_seconds: type: integer violations: type: array items: type: object properties: type: type: string path: type: string severity: type: string description: Adaptive Card TRUST-layer rejections (statusCode 422). 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: AgentKeyAuth: type: http scheme: bearer description: >- A trusted agent key (`bs_agent___`), shown once when you register the agent in the Console under Agents Ask → Trusted Agents. Scoped to one agent and one environment. ````