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":"[email protected]","phone":null},"timeout_seconds":3600}'
{
"success": true,
"data": {
"enabled": true,
"rules": [
{
"id": "review-email",
"tool": "email",
"when": {
"always": true
},
"action": "require_approval"
}
],
"approver": {
"email": "[email protected]",
"phone": null
},
"timeout_seconds": 3600
}
}
Approvals
Set action policy
Replace the agent’s action policy
PUT
/
v1
/
agents
/
me
/
action-policy
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":"[email protected]","phone":null},"timeout_seconds":3600}'
{
"success": true,
"data": {
"enabled": true,
"rules": [
{
"id": "review-email",
"tool": "email",
"when": {
"always": true
},
"action": "require_approval"
}
],
"approver": {
"email": "[email protected]",
"phone": null
},
"timeout_seconds": 3600
}
}
Replaces the entire policy. Omitted fields reset to defaults; they do not retain stored values.
All conditions in a rule must match;
A goal can lower its caps and add quiet time with
Authentication
X-Agent-ID plus a signed x-agent-proof with scope: "write". See proof 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.
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":"[email protected]","phone":null},"timeout_seconds":3600}'
Parameters
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.email (valid address, at most 320 characters) and/or phone (E.164). Required for any require_approval rule. Omitted contacts become null.Daily send limits, per UTC day.
per_agent and per_goal each map a channel (email, sms, voice, linkedin, commerce) to a whole number from 0 to 1,000,000. Omitted channels keep the defaults. See outbound limits.start and end (HH:MM): the local period in which no text or call goes out, in the recipient’s time zone. Default 21:00 to 08:00.deny wins. Each when needs at least one condition.
Response
200 returns the saved policy fields.
{
"success": true,
"data": {
"enabled": true,
"rules": [
{
"id": "review-email",
"tool": "email",
"when": {
"always": true
},
"action": "require_approval"
}
],
"approver": {
"email": "[email protected]",
"phone": null
},
"timeout_seconds": 3600
}
}
400 invalid_action_policy includes message and, for invalid rules, an errors array. 500 action_policy_write_failed means saving failed.
Outbound limits
Every send is checked, with or without rules, before it is charged: the suppression list, daily caps per agent and per goal, and quiet hours in the recipient’s zone:recipient_timezone on the send, else the case’s location, else the number.
| Channel | Default per agent and per goal |
|---|---|
email | 2,000 |
sms | 1,000 |
voice | 500 |
linkedin | 300 |
commerce | 50 |
params.outbound_limits, never raise them. See refusals.
{ "daily_caps": { "per_agent": { "sms": 200 }, "per_goal": { "sms": 50 } }, "quiet_hours": { "start": "20:00", "end": "09:00" } }
Held calls
A matchingrequire_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:
{
"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. Poll it, then retry the same call with X-Approval-Id once approved. See held-call behavior.