> ## 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.

# Set action policy

> Replace the agent’s action policy

Replaces the entire policy. Omitted fields reset to defaults; they do not retain stored values.

## Authentication

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

Requires a wallet session signed by the agent wallet. An access token can only read; writes return `403 action_policy_read_only_for_access_tokens`.

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://win.oneshotagent.com/v1/agents/me/action-policy" \
    -H "X-Agent-ID: 0xYourWalletAddress" \
    -H "x-agent-proof: <base64 signed proof, scope=write>" \
    -H "Content-Type: application/json" \
    -d '{"enabled":true,"rules":[{"id":"review-email","tool":"email","when":{"always":true},"action":"require_approval"}],"approver":{"email":"ops@acme.com","phone":null},"timeout_seconds":3600}'
  ```
</RequestExample>

## Parameters

<ParamField body="enabled" type="boolean" default="true">Set `false` to disable this policy.</ParamField>
<ParamField body="rules" type="object[]" default="[]">At most 25 rules. Each requires `tool`, `when` and `action` (`require_approval` or `deny`). Optional `id`: 1-64 characters from `[A-Za-z0-9_.-]`. See [tools and conditions](/api-reference/approvals/overview#action-policy).</ParamField>
<ParamField body="approver" type="object">`email` (valid address, at most 320 characters) and/or `phone` (E.164). Required for any `require_approval` rule. Omitted contacts become `null`.</ParamField>
<ParamField body="timeout_seconds" type="integer" default="3600">60-604800 seconds.</ParamField>

All conditions in a rule must match; `deny` wins. Each `when` needs at least one condition.

## Response

`200` returns the saved [policy fields](/api-reference/approvals/get-action-policy#response).

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "enabled": true,
      "rules": [
        {
          "id": "review-email",
          "tool": "email",
          "when": {
            "always": true
          },
          "action": "require_approval"
        }
      ],
      "approver": {
        "email": "ops@acme.com",
        "phone": null
      },
      "timeout_seconds": 3600
    }
  }
  ```
</ResponseExample>

`400 invalid_action_policy` includes `message` and, for invalid rules, an `errors` array. `500 action_policy_write_failed` means saving failed.

## Held calls

A matching `require_approval` rule makes the protected call return `403 approval_required` before it runs or is charged. This is a response from the protected endpoint, not this policy endpoint. Response excerpt:

```json theme={null}
{
  "error": "approval_required",
  "status": "pending_approval",
  "message": "This email call needs a human approval (rule review-email). It was not run or charged. Retry the same call with X-Approval-Id once approved.",
  "approval_id": "appr_01J...",
  "approval": { "approval_id": "appr_01J...", "source": "policy", "tool": "email", "status": "pending", "policy_rule": "review-email" }
}
```

`approval` is the full [approval object](/api-reference/approvals/get#response). [Poll it](/api-reference/approvals/get), then retry the same call with `X-Approval-Id` once approved. See [held-call behavior](/api-reference/approvals/overview#when-a-call-is-held).


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