Python SDK

The official Python package is named actionbox-sdk; the import is actionbox. It requires Python 3.11 or newer and must only be used in trusted server, worker, or CI environments.

Install

pip install actionbox-sdk

import os
from actionbox import Actionbox

with Actionbox(os.environ["ACTIONBOX_API_KEY"]) as client:
    decision = client.ask(
        title="Deploy to production?",
        options=["Approve", "Reject"],
        callback_url="https://ci.example.com/actionbox",
        context_request_mode="callback",
    )
    print(decision)

Customer integrations use ActionBox's hosted API at https://api.actionbox.cloud. Do not expose Source API keys or Watch capability URLs in browser code.

Use context_request_mode="poll" only when the integration monitors Action updates and can add requested information. Use "callback" with a callback_url when the handler supports action.context_requested. The default "unsupported" mode keeps the reviewer control hidden for static scripts.

Route to a reviewer

client.create(title="Review the migration", assignee_email="reviewer@example.com")
# Or use assignee_user_id="usr_..." for stored automation config.

# Team: restrict discovery and allow either reviewer to decide.
client.create(
    title="Approve emergency access",
    visibility="restricted",
    reviewer_emails=["incident@example.com", "security@example.com"],
)

Copy an ID from Settings → Team. Send email or ID, not both. See Assignments and routing for the compact schema.

Add a typed approval_policy to require votes from any reviewer, every reviewer, or a quorum. Polling exposes approval_progress and continues until the Action is terminal. Source-authenticated SDK clients cannot cast human votes. See Approval Policies.

Typed interactions

Use create with typed interactions when a response is more than a single choice. Supported types include boolean, single choice, multiple choice, text, integer, number, rating, and form.

from actionbox import BooleanInteraction

action = client.create(
    title="Deploy configuration",
    interaction=BooleanInteraction(
        type="boolean",
        label="Deploy now?",
        true_label="Deploy",
        false_label="Hold",
    ),
)

After executing an approved operation, report its real outcome from the resolved Action snapshot:

resolved.report_outcome("success", duration_ms=48_312, rollback=False)

See Actions, interaction types, and decisions and outcomes for the underlying contract.