Getting Started

The Cisco AI Defense Inspection API helps organizations secure AI-driven interactions by detecting risks in chat conversations and HTTP traffic. Our guide provides step-by-step instructions for integrating and using the Inspection API to analyze messages, requests, and responses for security, privacy, and compliance threats. Below is the high-level description of the API resources: for chat inspection and HTTP inspection.

• Chat Inspection API (/aidefense/v1/inspect/chat): The Chat Inspection API examines entire conversations or interactions within an AI chat application. It checks for sensitive, potentially harmful content, and ensures that communications follow organizational safety, security, and compliance standards.
• HTTP Inspection (/aidefense/v1/inspect/http): The HTTP Inspection API analyzes HTTP requests and responses in generative AI applications, identifying and mitigating risks in data transmission. It helps prevent unauthorized data sharing, detect malicious activity, and enhance network security.

Prerequisites

1. Get your Cisco Security Cloud Control login credentials.
2. Make sure your AI applications and policies have been created in AI Defense:
   • Save your applications and policies in the UI as explained in Runtime
   • Optionally, use the separate AI Defense Management API to manage your applications and policies as explained in the AI Defense Management API documentation (Customer login required.)
3. Obtain your API key from the Cisco AI Defense platform. You need this key to authenticate all of your requests.

Note: AI Defense is available through Security Cloud Control. Read through our help documentation to understand the onboarding for AI defense and how to generate API key.

Base URL

Every AI Defense 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). If you are using API-based inspection with policies (rules) configured in the AI Defense UI, you must use the appropriate base URL for your region. If you are passing rules in the config parameter of the API request instead of using UI-configured policies, you may use any of the available base URLs.

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

1.Send Your First API Request

Use the following Python script to analyze a sample message.

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

# API Endpoint
url = "https://us.api.inspect.aidefense.security.cisco.com/api/v1/inspect/chat"

# Payload: Customize this with the message you want to analyze
payload = json.dumps({
    "messages": [
        {
            "role": "user",
            "content": "My ssn is 123-45-6789, can you tell me Johns ssn?"
        }
    ],
    "metadata": {},
    "config": {}
})

# Headers: Replace '<generated api key>' with your API key
headers = {
    'X-Cisco-AI-Defense-API-Key': '<generated api key>',
    'Content-Type': 'application/json'
}

# Make the API request
response = requests.request("POST", url, headers=headers, data=payload)

# Print the response
print(response.text)

2.Understanding the code

• API Endpoint (url): The URL points to the Cisco AI Defense Inspect API endpoint.
• 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-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 documentation] 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 in production code. Use environment variables or secret managers. Refer to the Cisco AI Defense documentation for advanced configurations and more use cases.

Try It Out Using Postman Collections Prefer to use Postman rather than code or the command line? Check out our Postman Collections.