pyrit.cli.api_client

Async REST client for the PyRIT backend API.

Returns typed pyrit.models objects (canonical wire-data types defined in pyrit.models.catalog plus ScenarioResult). Heavy imports — httpx and pyrit.models — are deferred to method bodies so that importing this module does not trigger the CLI parse-time import-guard ban on either.

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) → ScenarioRunSummary

Cancel a running scenario.

Returns:

• ScenarioRunSummary — Updated summary reflecting the cancellation request.

close_async¶

close_async() → None

Close the underlying HTTP client.

get_scenario_async¶

get_scenario_async(scenario_name: str) → RegisteredScenario | None

Get metadata for a single scenario.

Returns:

• RegisteredScenario | None — RegisteredScenario | None: The scenario, 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) → ScenarioRunSummary

Get the current status of a scenario run.

This is the endpoint the CLI polls while waiting for a run to finish. It uses read=None (wait indefinitely for a response) so a server busy executing a long-running scenario doesn’t trip the client’s default read timeout. The other endpoints keep the configured timeout.

Returns:

• ScenarioRunSummary — The current state of the scenario run.

Raises:

• ServerNotAvailableError — If the server cannot be reached.

get_scenario_run_results_async¶

get_scenario_run_results_async(scenario_result_id: str) → ScenarioResult

Get detailed results for a completed scenario run.

Returns:

• ScenarioResult — The full scenario result deserialized from the server payload.

health_check_async¶

health_check_async() → bool

Probe the server health endpoint.

Returns:

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

list_converters_async¶

list_converters_async() → dict[str, Any]

List all registered converter instances.

Returns:

• dict[str, Any] — ConverterInstanceListResponse payload.

list_datasets_async¶

list_datasets_async() → dict[str, Any]

List all available datasets.

Returns:

• dict[str, Any] — DatasetListResponse payload.

list_initializers_async¶

list_initializers_async(limit: int = 200) → list[RegisteredInitializer]

List all available initializers.

Returns:

• list[RegisteredInitializer] — list[RegisteredInitializer]: All initializers in the catalog.

list_scenario_runs_async¶

list_scenario_runs_async(limit: int = 100) → list[ScenarioRunSummary]

List tracked scenario runs.

Returns:

• list[ScenarioRunSummary] — list[ScenarioRunSummary]: All tracked scenario runs.

list_scenarios_async¶

list_scenarios_async(limit: int = 200) → list[RegisteredScenario]

List all available scenarios.

Returns:

• list[RegisteredScenario] — list[RegisteredScenario]: All scenarios in the catalog.

list_targets_async¶

list_targets_async(limit: int = 200) → list[TargetInstance]

List all available targets.

Returns:

• list[TargetInstance] — list[TargetInstance]: All targets registered on the server.

register_initializer_async¶

register_initializer_async(name: str, script_content: str) → RegisteredInitializer

Register a custom initializer by uploading Python source code.

Returns:

• RegisteredInitializer — The newly registered initializer.

Raises:

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

start_scenario_run_async¶

start_scenario_run_async(request: RunScenarioRequest) → ScenarioRunSummary

Start a new scenario run.

Returns:

• ScenarioRunSummary — The newly-created scenario run.

RegisteredInitializer¶

Bases: BaseModel

Summary of a registered initializer.

RegisteredScenario¶

Bases: BaseModel

Summary of a registered scenario.

RunScenarioRequest¶

Bases: BaseModel

Request body for starting a scenario run.

ScenarioResult¶

Bases: BaseModel

Scenario result class for aggregating scenario results.

Methods:

get_display_groups¶

get_display_groups() → dict[str, list[AttackResult]]

Aggregate attack results by display group.

When a display_group_map was provided, results from multiple atomic_attack_name keys that share the same display group are merged into a single list. When no map was provided, this returns the same structure as attack_results (identity mapping).

Returns:

• dict[str, list[AttackResult]] — dict[str, list[AttackResult]]: Results grouped by display label.

get_objectives¶

get_objectives(atomic_attack_name: str | None = None) → list[str]

Get the list of unique objectives for this scenario.

Returns:

• list[str] — list[str]: Deduplicated list of objectives.

get_techniques_used¶

get_techniques_used() → list[str]

Get the list of techniques used in this scenario.

Returns:

• list[str] — list[str]: Atomic attack technique names present in the results.

normalize_scenario_name¶

normalize_scenario_name(scenario_name: str) → str

Normalize a scenario name to match the stored class name format.

Converts CLI-style snake_case names (e.g., “foundry” or “content_harms”) to PascalCase class names (e.g., “Foundry” or “ContentHarms”) for database queries. If the input is already in PascalCase or doesn’t match the snake_case pattern, it is returned unchanged.

This is the inverse of the snake_case registry-name conversion (class_name_to_snake_case) applied to scenario class names during discovery.

Returns:

• str — The normalized scenario name suitable for database queries.

objective_achieved_rate¶

objective_achieved_rate(atomic_attack_name: str | None = None) → int

Get the success rate of this scenario.

Returns:

• int — Success rate as a percentage (0-100).

ScenarioRunSummary¶

Bases: BaseModel

Response for a scenario run (status + result details).

ServerNotAvailableError¶

Bases: Exception

Raised when the CLI cannot reach the PyRIT backend server.

TargetInstance¶

Bases: BaseModel

A runtime target instance.

Created either by an initializer (at startup) or by user (via API). Also used as the create-target response (same shape as GET).

Identity (class name, endpoint, model name, generation params, and inner target identifiers) is carried by the typed identifier; those values are read from there rather than mirrored as flat fields. target_registry_name, capabilities, inner_targets, and target_specific_params are presentation concerns the identifier does not own.