> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ask for approval

> Ask a named person to approve an action

Creates an informational approval. It cannot release a held paid call. At most 20 pending approvals per agent.

## Authentication

`X-Agent-ID` plus a signed `x-agent-proof` with `scope: "write"`. See [proof authentication](/sdk/overview#read-authentication).

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://win.oneshotagent.com/v1/approvals" \
    -H "X-Agent-ID: 0xYourWalletAddress" \
    -H "x-agent-proof: <base64 signed proof, scope=write>" \
    -H "Content-Type: application/json" \
    -d '{"action_summary":"Send the signed LOI to Acme","preview":{"contact":"jane@acme.com"},"approver":{"email":"ops@acme.com"},"expires_in_seconds":3600}'
  ```
</RequestExample>

## Parameters

<ParamField body="action_summary" type="string" required>Nonblank summary, 1-2000 characters. Alias: `summary`.</ParamField>
<ParamField body="approver" type="object" required>At least one of `email` (valid address, at most 320 characters) or `phone` (E.164). Email is used when both are supplied.</ParamField>
<ParamField body="preview" type="object | null">Optional details shown to the approver, at most 4000 characters when JSON-encoded.</ParamField>
<ParamField body="expires_in_seconds" type="integer" default="3600">60-604800 seconds. Alias: `timeout_seconds`. Unanswered requests expire.</ParamField>

## Response

`201` returns the [approval object](/api-reference/approvals/get#response). Check `notified` and `notify_error` for delivery failures.

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "approval_id": "appr_01J...",
      "source": "api",
      "tool": null,
      "status": "pending",
      "action_summary": "Send the signed LOI to Acme",
      "preview": {
        "contact": "jane@acme.com"
      },
      "policy_rule": null,
      "approver": {
        "channel": "email",
        "address": "o***@acme.com"
      },
      "expires_at": "2026-10-19T13:00:00.000Z",
      "use_by": null,
      "decided_at": null,
      "decided_via": null,
      "decision_note": null,
      "decision_receipt_id": null,
      "consumed_at": null,
      "notified": true,
      "notify_error": null,
      "compute": null,
      "created_at": "2026-10-19T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

`400 invalid_approval` means a field failed validation. `429 too_many_pending_approvals` means the pending limit was reached.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.