pyrit.cli.api_client

Async REST client for the PyRIT backend API.

Uses httpx internally but defers the import to method calls so that importing this module does not trigger the import-guard ban on httpx at CLI parse time.

PyRITApiClient¶

Lightweight async REST client for the PyRIT backend.

No heavy pyrit imports.

Use as an async context manager::

async with PyRITApiClient(base_url="http://localhost:8000") as client:
    scenarios = await client.list_scenarios_async()

Constructor Parameters:

Methods:

cancel_scenario_run_async¶

cancel_scenario_run_async(scenario_result_id: str) → dict[str, Any]

Cancel a running scenario.

Returns:

• dict[str, Any] — Updated ScenarioRunSummary payload.

close_async¶

close_async() → None

Close the underlying HTTP client.

get_scenario_async¶

get_scenario_async(scenario_name: str) → dict[str, Any] | None

Get metadata for a single scenario.

Returns:

• dict[str, Any] | None — dict | None: RegisteredScenario payload, or None if 404.

Raises:

• httpx.HTTPStatusError — For non-404 HTTP error responses.

get_scenario_run_async¶

get_scenario_run_async(scenario_result_id: str) → dict[str, Any]

Get the current status of a scenario run.

Returns:

• dict[str, Any] — ScenarioRunSummary payload.

get_scenario_run_results_async¶

get_scenario_run_results_async(scenario_result_id: str) → dict[str, Any]

Get detailed results for a completed scenario run.

Returns:

• dict[str, Any] — ScenarioResult.to_dict() payload.

health_check_async¶

health_check_async() → bool

Probe the server health endpoint.

Returns:

• bool — True if the server returned a healthy response.

list_initializers_async¶

list_initializers_async(limit: int = 200) → dict[str, Any]

List all available initializers.

Returns:

• dict[str, Any] — ListRegisteredInitializersResponse payload.

list_scenario_runs_async¶

list_scenario_runs_async(limit: int = 100) → dict[str, Any]

List tracked scenario runs.

Returns:

• dict[str, Any] — ScenarioRunListResponse payload.

list_scenarios_async¶

list_scenarios_async(limit: int = 200) → dict[str, Any]

List all available scenarios.

Returns:

• dict[str, Any] — ListRegisteredScenariosResponse payload.

list_targets_async¶

list_targets_async(limit: int = 200) → dict[str, Any]

List all available targets.

Returns:

• dict[str, Any] — TargetListResponse payload.

register_initializer_async¶

register_initializer_async(name: str, script_content: str) → dict[str, Any]

Register a custom initializer by uploading Python source code.

Returns:

• dict[str, Any] — RegisteredInitializer payload.

Raises:

• ServerNotAvailableError — If custom initializers are disabled (403).

start_scenario_run_async¶

start_scenario_run_async(request: dict[str, Any]) → dict[str, Any]

Start a new scenario run.

Returns:

• dict[str, Any] — ScenarioRunSummary payload.

ServerNotAvailableError¶

Bases: Exception

Raised when the CLI cannot reach the PyRIT backend server.