Getting Started

The Cisco AI Defense Management API helps organizations secure AI applications by registering them with AI Defense and running AI validation to test models for security and safety vulnerabilities. Use this API in conjuntion with the AI Defense Inspection API to fully secure your AI applications and models.

This guide provides step-by-step instructions for integrating and using the API to register your AI applications and models in AI Defense and run AI Defense validation on them. Below, we show high-level descriptions of the API resources for:

• AI runtime protection set-up and management: The endpoints in the Applications (ai-defense/v1/applications), Connections (ai-defense/v1/connections), and Policies (ai-defense/v1/policies) sections allow you to set up and manage AI Defense runtime protection. The applications and connections endpoints let you manage connection details so that AI Defense runtime protection can connect to your AI applications and protect them. The policies endpoints allow you to manage the AI Defense policies and rules that protect your applications and models and their users.

• AI runtime protection event monitoring: The endpoints in the (ai-defense/v1/applications) section allow you to retrieve and inspect the events that AI Defense runtime protection generates when it detects a violation of your AI safety and security policies.

• AI model validation: The endpoints in the (ai-defense/v1/AiValidationAPI) section allow you to start AI model validation runs and get their results.

Prerequisites

1. Cisco Security Cloud Control login credentials.
2. Generate your API key in the Cisco AI Defense UI as explained in API keys. You need this key to authenticate each API request.

Note: API keys used for the AI Defense Management API are not interchangeable with API keys used in the AI Defense Inspection API. See API keys for details.

Base URL

Every AI Defense Management API request starts with a base URL specific to your deployment region. Use the correct base URL based on where your AI Defense instance was created when claiming your subscription in Security Cloud Control (SCC). For example, a North American base URL will include us. as shown here:

Here's an example of the most common North American base URL for the API:

https://api.us.security.cisco.com/

See API Keys and URLs for a complete list of base URLs. Below, we list the most common base URLs.

The regional base URLS are as follows:

Note: AI Defense instances deployed in North America have the option to omit the us. prefix and use the base URL, https://api.security.cisco.com/.

Make API Calls

1. Send Your First API Request

Use the following Python script to retrieve a list of the applcations your administrators have saved in AI Defense.

import json
import requests  # Ensure you have the 'requests' library installed

# Specify the API Endpoint. Replace 'us.' with your regional prefix.
url = "https://api.us.security.cisco.com/api/ai-defense/v1/applications"

# Set up the headers: Replace '<generated api key>' with your API key
headers = {
    'Accept': 'application/json',
    'x-cisco-ai-defense-tenant-api-key': '<generated api key>'
}

# Make the API request
response = requests.request("GET", url, headers=headers)

# Print the response
print(response.text)

2. Understanding the code

• API Endpoint (url): The URL points to the Cisco AI Defense Inspect API endpoint. Replace 'us.' with your regional prefix.
• Payload:
  • messages: An array of objects, where each object represents a message. Customize the content with the text that you want to analyze.
  • metadata: (Optional) Include additional information, such as timestamps or user IDs, for contextual analysis.
  • config: (Optional) Add specific configuration settings for the API.
• Headers:
  • Include the API key in the x-cisco-ai-defense-tenant-api-key header. Replace with your actual API key.
  • Set the Content-Type to application/json to ensure that the payload is sent in JSON format.
• Making the Request: Use the requests.request method to send a POST request with the URL, headers, and payload.
• Response: The API returns a JSON response. Use print(response.text) to view the results.

3. Understanding API Responses

Analyze the JSON response to understand how the system detects or flags sensitive content.

4. Error Handling

If something goes wrong, the API returns an error code.

• Ensure that all request parameters are correctly formatted.
• Verify API authentication credentials (e.g., API key).
• Check integration settings to use valid values.
• Refer to the API Reference for more details on proper request structure.

Note: See our list of AI Defense Error codes.

Example:

   
if response.status_code == 200:
    print("Success:", response.json())
else:
    print("Error:", response.status_code, response.text)

Note: Keep your API key secure. Never hardcode it into your production code. Use environment variables or secret managers. Refer to the Cisco AI Defense documentation for advanced configurations and more use cases.