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":"[email protected]"},"approver":{"email":"[email protected]"},"expires_in_seconds":3600}'
{
"success": true,
"data": {
"approval_id": "appr_01J...",
"source": "api",
"tool": null,
"status": "pending",
"action_summary": "Send the signed LOI to Acme",
"preview": {
"contact": "[email protected]"
},
"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"
}
}
Approvals
Ask for approval
Ask a named person to approve an action
POST
/
v1
/
approvals
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":"[email protected]"},"approver":{"email":"[email protected]"},"expires_in_seconds":3600}'
{
"success": true,
"data": {
"approval_id": "appr_01J...",
"source": "api",
"tool": null,
"status": "pending",
"action_summary": "Send the signed LOI to Acme",
"preview": {
"contact": "[email protected]"
},
"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"
}
}
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.
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":"[email protected]"},"approver":{"email":"[email protected]"},"expires_in_seconds":3600}'
Parameters
string
required
Nonblank summary, 1-2000 characters. Alias:
summary.object
required
At least one of
email (valid address, at most 320 characters) or phone (E.164). Email is used when both are supplied.object | null
Optional details shown to the approver, at most 4000 characters when JSON-encoded.
integer
default:"3600"
60-604800 seconds. Alias:
timeout_seconds. Unanswered requests expire.Response
201 returns the approval object. Check notified and notify_error for delivery failures.
{
"success": true,
"data": {
"approval_id": "appr_01J...",
"source": "api",
"tool": null,
"status": "pending",
"action_summary": "Send the signed LOI to Acme",
"preview": {
"contact": "[email protected]"
},
"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"
}
}
400 invalid_approval means a field failed validation. 429 too_many_pending_approvals means the pending limit was reached.