API Changelog

Version 1.3

v1.3.0 - 2026-06-25

In API version 1.3 (released with the AI Defense 26.6.4 release), AI Defense introduces modular validation. This is a significant refactoring of how you set up and run agent, model, and application validations in AI Defense. With modular validation, we have decoupled the set-up of validation targets (the agents, models, and applications you’re testing) and validation profiles (which tests you’ll run and how the tests are configured) from the individual job executions.

Where previously you had to configure all aspects of your validation at the time you started the test, now you can save validation targets and profiles and reuse them. This relieves you of the burden of repetitive, one-off configuration of validation runs. Now, when you kick off a validation run, you simply pass in the pre-saved target and profile that define your test.

The AI Validation workflow is modularized

The API now provides target and profile objects to configure your validation tests. This avoids the need for repetitive, one-off validation configurations while retaining support for your code that uses our earlier approach.

• Start Validation endpoint: The endpoint used to initiate a validation run remains the same: POST /ai-validation/start (and the multi-turn version /ai-validation/start/multi). However, the v1StartAiValidationRequest definition has changed to reflect the shift toward using target_id and profile_id. Instead of providing raw configuration strings like model_endpoint_url or model_request_template in every call, the user now references the pre-saved objects.

The new workflow

1. Create/Save Target: The user calls POST /ai-validation/targets to save the model/application endpoint, credentials, and connection details. The system returns a target_id.
2. Create/Save Profile: The user calls POST /ai-validation/profiles to save the testing configuration (language, content categories, custom goals). The system returns a profile_id.
3. Initiate the validation run: The user calls POST /ai-validation/start and passes the target_id and profile_id (along with any necessary overrides) in the request body.

Backward compatibility is maintained: Along with the new modular design, AI Defense continues to support its earlier approach in which you configure the validation run at the time you start it with the v1StartAiValidationRequest endpoint.

Target-centric validation workflow: The List AI Validation Jobs endpoint now includes a target_id filter, allowing users to track jobs associated with a specific agent, model, or application.

More granular validation results

A new endpoint, Get AI Validation Result (/ai-validation/results/{task_id}/{attack_id}), has been added to retrieve specific attack results, providing more granular access to validation data than the previous list-only approach.

Custom validation goals

New endpoints (Create AI Validation Custom Goals /ai-validation/custom-goals and related endpoints) let you create your own attack goals that will be run during a validation, for example to test against risks specific to your industry.

New ways to manage connection, test, and credential configurations

• Target Management: New endpoints have been introduced to manage "Validation Targets" (/ai-validation/targets). Users can now save connection details (AWS Bedrock, Custom Endpoints, AWS AgentCore) as reusable targets, which include information like system prompts and request-per-minute limits.
• Profile Management: New endpoints for "Validation Profiles" (/ai-validation/profiles) allow users to define reusable testing configurations (e.g., language, multi-turn settings, and content categories).
• IdP Configuration: A new IdpConfigService has been added (/auth/idp) to support JWT validation against identity providers.
• Connector Management: A new Connectors tag and associated endpoints (/connector, /connectors) have been added to manage AI Defense connector instances.

Updated Schema Definitions

To support the new modular workflow and other features, several definitions were added or updated:

• Target definitions: v1TargetSummary, v1GetTargetResponse, v1CreateTargetRequest, and provider-specific configs (v1AwsBedrockProviderConfig, v1AwsAgentCoreProviderConfig, v1CustomProviderConfig).
• Profile definitions: v1ValidationProfile, v1CreateAiValidationProfileRequest, and v1ProfileUpdate.
• Connector definitions: v1Connector, v1CreateConnectorRequest, and v1HybridEnvironment.
• Identity provider (IdP) definitions: v1IdpConfig, v1CreateIdpConfigRequest, and v1ValidateIdpConfigRequest.
• Expanded language support: The generativevalidationLanguage enum has been expanded to include Spanish (LANGUAGE_ES), Italian (LANGUAGE_IT), and Arabic (LANGUAGE_AR).

Summary of key additions in API version 1.3

Version 1.2

v1.2.0 - 2026-02-03

New endpoint: POST /ai-validation/start/multi

Start a multi-turn AI validation job

Starts a multi-turn AI validation job for a model or application. Multi-turn validations probe the model with multiple prompts in a conversation to try to elicit undesirable model behavior. This endpoint triggers the validation process and returns a task ID. Use the task ID to call the GET /ai-validation/results/{task_id} endpoint to retrieve the results of your validation run.

See also the existing non-multi-turn start endpoint for starting a single-turn validation. (Single-turn validations probe the model with discrete prompts that are not part of a longer conversation.)

New endpoint: GET /ai-validation/config/{task_id}

Get AI Validation Config

Retrieves the AI validation configuration for a specific task ID. This includes details about the model under test, request templates, and the configuration parameters used to test the model.

New endpoint: DELETE /ai-validation/jobs/{task_id}

Delete AI Validation Job

Deletes the AI validation job identified by the provided task_id.

New beta-release endpoints for MCP server scanning

The following new, beta-release endpoints allow you to register and scan MCP servers for safety:

• Register a new MCP server (POST /mcp/servers) registers a new MCP server with AI Defense for subsequent scanning.
• Get MCP server by ID (GET /mcp/servers/{id}) returns the registration information and scan settings for an MCP server you've registered with AI Defense.
• List MCP servers (GET /mcp/servers) lists registered MCP servers.
• Scan MCP server without registration (POST /mcp/servers/scan) runs a one-time scan of an MCP server without requiring the server's registration in AI Defense.
• Get Scan status for MCP server scan (GET /mcp/servers/scan/{scan_id}) returns information about the most recent scan of an MCP server.
• Delete MCP server (DELETE /mcp/servers/{id}) deletes the registration information and scan settings for an MCP server you've registered with AI Defense.

New beta-release endpoints for managing resource connections

The following new, beta-release endpoints allow you to manage resource connections in AI Defense:

• Create resource connection (POST /resource/connections) creates a connection.
• Get resource connection by resource ID (GET /resource/{resource_id}/connection) retrieves a resource connection by its resource ID.
• Get resource connection by ID (GET /resource/connections/{connection_id}) retrieves a resource connection by its connection ID.
• Filter resources by connection ID (POST /resource/connection/{connection_id}/resources) retrieves resources associated with the given connection ID.
• Filter resource connections (POST /resource/connections/filter) returns a filtered list of resource connections based on specified criteria.
• Add or update resource connections (PUT /resource/connections/{connection_id}) associates or disassociates resources with a given connection ID.
• Delete resource connection (DELETE /resource/connections/{connection_id}) deletes a resource connection by its connection ID.

Version 1.1

v1.1.0 - 2025-12-09

New endpoint: GET /ai-validation/jobs

List AI Validation Jobs

Retrieves a list of AI validation jobs with comprehensive filtering, sorting, and offset-based pagination support. Follows standard product pagination pattern with limit/offset. Includes detailed job information, configuration details, and attack counts.

New endpoint: POST /ai-validation/start/multi

Start AI Validation in multi-turn mode

Starts a multi-turn AI validation job for a model or application. This endpoint triggers the validation process and returns a task ID.

New endpoint: DELETE /ai-validation/jobs/{task_id}

Delete an AI validation job by its task ID.

New endpoint: GET /ai-validation/results/{task_id}

Get AI validation results

Retrieves the AI validation results for a specific validation run, based on the task_id you specify. This includes the job status, progress, and timestamps.

New endpoint: GET /scans

List all model supply chain scans.

New endpoint: GET /scans/{scan_id}

Get status of a specific model supply chain scan by its ID.

Version 1.0

v1.0.0 - 2025-07-23

The initial release of Cisco AI Defense Management API.