CalypsoAI
Search K

Appearance

Getting started with Inference Defend ​

ROLES AND PERMISSIONS

To complete the tasks described in this section, make sure you have the required permissions.

Learn the basics of using our Defend product.

With Defend, you can create and use scanners to secure usage of your applications and LLMs (Large Language Models) against threats such as prompt injection, jailbreaking, and data exfiltration.

Scanners are the core capability of our Defend product. They are real-time policies for monitoring and intercepting traffic coming in and out of your LLMs and applications, acting as policies with detection rules. Scanners identify undesirable content based on keywords, regular expressions, AI-generated definitions, or our own proprietary scanning models.

You can use the default CalypsoAI scanners or create your own custom scanners.

  • Default scanners: The CalypsoAI Platform comes with several out-of-the-box scanner packages created by our research team. These scanners protect against the most common risks associated with AI systems. To ensure the most comprehensive protection, we keep all our default scanners and scanner packages regularly updated.
  • Custom scanners: Create and configure your own custom GenAI, regex, or keyword scanners, tailored to your specific use cases and business needs.
    For more information, see Creating a custom scanner.

To get familiar with Defend, complete the following tasks:

  1. Send a scan request.
  2. Send a prompt to the default provider.
  3. Create a project.
  4. Add a scanner to a project.

SDK

The following requests and examples refer to our Python SDK, as this is the recommended way of interacting with CalypsoAI API.

Send a scan request ​

First, let's try sending a scan request.

Every scan request you send is verified by all available and enabled scanners. What scanners are available depends on the API token you provide, and the token can be either global or assigned to a project.

  • If the token is global, your scan request is sent to all globally available scanners.
  • If the token is project-specific, your scan request is sent to scanners defined in the project.

PREREQUISITES

Create your token.

To send a scan request:

  1. Add your token value to the following sample.

    python
    from calypsoai import CalypsoAI

# Define the URL and token for CalypsoAI
CALYPSOAI_URL = "https://www.us1.calypsoai.app"
CALYPSOAI_TOKEN = "ADD-YOUR-TOKEN-HERE"

# Initialize the CalypsoAI client
cai = CalypsoAI(url=CALYPSOAI_URL, token=CALYPSOAI_TOKEN)

# Send a scan request
prompt = cai.scans.scan("What is your name?")
print(prompt.model_dump_json(indent=2))

  2. Run the script.

  3. Analyze the response.
    The following response sample is a simplified version of a successful request, focusing only on the main details relevant to this specific request.

    json
    {
  "id": "01985bd2-bb2c-702d-9b9c-30e8ec065504",
  "input": "What is your name?",
  "result": {
    "outcome": "cleared",
    "scannerResults": [
      {
        "outcome": "passed",
        "scanDirection": "request",
        "scannerId": "01983d0c-f1cc-700a-ab56-6600efc7dfb9",
        "scannerVersionMeta": {
          "name": "v_1",
        },
      }
    ]
  },
  "type": "scan",
  "userId": "machine=0198560b-1ca8-7052-bde5-82898e17c4cf",
}

    The response includes the following key parameters:

    • id: The scan request ID.
    • input: The text being scanned.
    • result > outcome: The result of the scan.
      In this example, the scan request was not flagged by any scanners.
    • result > scannerResults: A list of every scanner that ran during the scan.
    • result > scannerResults > outcome: The outcome of each individual scanner that ran during the scan.
    • result > scannerResults > scanDirection: The scanning direction of each individual scanner that ran during the scan.
    • result > scannerResults > scannerVersionMeta > name: The name of the scanner version used during the run, for each individual scanner.
    • type: The scan type.
      In this example, the type is a scan request.
    • userId: The ID of the user or machine that ran the scan.
    To view the full response, click here.
    json
    {
  "externalMetadata": null,
  "id": "01985bd2-bb2c-702d-9b9c-30e8ec065504",
  "input": "What is your name?",
  "preserve": false,
  "projectId": "01951ee7-d3b7-70bd-9c11-12f73f967057",
  "receivedAt": "2025-07-30T14:53:13.900184Z",
  "result": {
    "outcome": "cleared",
    "scannerResults": [
      {
        "completedDate": "2025-07-30T14:53:14.066272Z",
        "customConfig": false,
        "data": {
          "type": "custom"
        },
        "outcome": "passed",
        "scanDirection": "request",
        "scannerId": "01983d0c-f1cc-700a-ab56-6600efc7dfb9",
        "scannerVersionMeta": {
          "createdAt": "2025-07-24T15:34:10.947982Z",
          "createdBy": null,
          "description": "",
          "id": "01983d12-1103-70ef-be4d-bb6e0eb4ddff",
          "name": "v_1",
          "published": true
        },
        "startedDate": "2025-07-30T14:53:13.903866Z"
      }
    ]
  },
  "type": "scan",
  "userId": "machine=0198560b-1ca8-7052-bde5-82898e17c4cf",
  "endpointId": "01951ee7-d3b7-70bd-9c11-12f73f967057"
}

Send a prompt to the default provider ​

Now, we are going to send a prompt to the default provider. Just like with scanners, what provider is configured as "default" depends on the API token you provide.

A prompt is text input sent to LLM providers for processing. Our scanners validate each prompt before sending, and can block flagged prompts, as well as responses to prompts.

PREREQUISITES

Add a provider.

To send a prompt:

  1. Add your token value to the following sample.

    python
    from calypsoai import CalypsoAI

# Define the URL and token for CalypsoAI
CALYPSOAI_URL = "https://www.us1.calypsoai.app"
CALYPSOAI_TOKEN = "ADD-YOUR-TOKEN-HERE"

# Initialize the CalypsoAI client
cai = CalypsoAI(url=CALYPSOAI_URL, token=CALYPSOAI_TOKEN)

# Send a prompt request
prompt = cai.prompts.send("What is your name?")
print(prompt.model_dump_json(indent=2))

  2. Run the script.

  3. Analyze the response.
    The following response sample is a simplified version of a successful request, focusing only on the main details relevant to this specific request.

    json
    {
  "id": "01985bd0-6e4b-70a3-94f6-7ac8f72706ad",
  "input": "What is your name?",
  "result": {
    "outcome": "cleared",
    "response": "I am called Assistant. How can I help you today?",
    "scannerResults": [
      {
        "outcome": "passed",
        "scanDirection": "response",
        "scannerId": "01983d0c-f1cc-700a-ab56-6600efc7dfb9",
        "scannerVersionMeta": {
          "name": "v_1",
        }
      }
    ]
  },
  "type": "prompt",
  "userId": "machine=0198560b-1ca8-7052-bde5-82898e17c4cf"
}

    The response includes the following key parameters:

    • id: The prompt scan request ID.
    • input: The text being scanned.
    • result > outcome: The result of the scan.
      In this example, the prompt was not flagged by any scanners.
    • result > scannerResults: A list of every scanner that ran during the scan.
    • result > scannerResults > outcome: The outcome of each individual scanner that ran during the scan.
    • result > scannerResults > scanDirection: The scanning direction of each individual scanner that ran during the scan.

      SCANNING DIRECTION

      If a scanner works in both directions, the request and the response results are presented as separate items.

    • result > scannerResults > scannerVersionMeta > name: The name of the scanner version used during the run, for each individual scanner.
    • type: The scan type.
      In this example, the type is a prompt.
    • userId: The ID of the user or machine that ran the scan.
    To view the full response, click here.
    json
    {
  "externalMetadata": null,
  "fromTemplate": false,
  "id": "01985bd0-6e4b-70a3-94f6-7ac8f72706ad",
  "input": "What is your name?",
  "memory": null,
  "orgId": null,
  "parentId": null,
  "preserve": false,
  "projectId": "01951ee7-d3b7-70bd-9c11-12f73f967057",
  "provider": "01953db0-fb71-7035-af13-ef2e37591557",
  "receivedAt": "2025-07-30T14:50:43.147654Z",
  "result": {
    "analysis": null,
    "files": null,
    "outcome": "cleared",
    "providerResult": {
      "data": "I am called Assistant. How can I help you today?",
      "input": null,
      "receivedDate": "2025-07-30T14:50:44.227745Z",
      "sentDate": "2025-07-30T14:50:43.318925Z",
      "statusCode": 200
    },
    "response": "I am called Assistant. How can I help you today?",
    "scannerResults": [
      {
        "completedDate": "2025-07-30T14:50:44.342269Z",
        "customConfig": false,
        "data": {
          "type": "custom"
        },
        "outcome": "passed",
        "scanDirection": "response",
        "scannerId": "01983d0c-f1cc-700a-ab56-6600efc7dfb9",
        "scannerVersionMeta": {
          "createdAt": "2025-07-24T15:34:10.947982Z",
          "createdBy": null,
          "description": "",
          "id": "01983d12-1103-70ef-be4d-bb6e0eb4ddff",
          "name": "v_1",
          "published": true
         },
         "startedDate": "2025-07-30T14:50:44.227764Z"
      }
    ]
  },
  "type": "prompt",
  "userId": "machine=0198560b-1ca8-7052-bde5-82898e17c4cf",
  "endpointId": "01951ee7-d3b7-70bd-9c11-12f73f967057"
}

Create a project ​

After testing prompts and scans, it's time to create the first project. Projects allow you to create different scanner configurations, and manage access to specific models for selected groups of users assigned to a project.

To create a project:

  1. Edit the following sample.

    python
    from calypsoai import CalypsoAI
from calypsoai.datatypes import ProjectType

# Define the URL and token for CalypsoAI
CALYPSOAI_URL = "https://www.us1.calypsoai.app"
CALYPSOAI_TOKEN = "ADD-YOUR-TOKEN-HERE"

# Initialize the CalypsoAI client
cai = CalypsoAI(url=CALYPSOAI_URL, token=CALYPSOAI_TOKEN)

# Get all provider names
provider_names = [provider for provider in cai.providers.getAllByName()]

# Get the first provider
provider = cai.providers.get(provider_names[0])

# Create a new project
project = cai.projects.create(
    name="ADD-YOUR-PROJECT-NAME-HERE",
    projectType=ProjectType.APP,
    admins=['ADD-USER-ID-HERE'],
    providers=[provider.id],
    friendlyId="ADD-FRIENDLY-ID-HERE"
)

# Print the response
print(project.model_dump_json(indent=2))
    • Add your token value.
    • In cai.projects.create, do the following:
      • In name, provide a name for the project.
      • In projectType, specify the relevant type of project.
        The available values are app, chat and bot.
      • In admins, provide a list of user IDs for your project administrators.
        Administrators manage projects, for example, by adding providers, configuring scanners, or creating dedicated tokens.
      • In providers, provide a list of IDs for providers to which you want to have access in the project.
      • In friendlyId, provide a friendly ID for the project.
        This is an optional parameter. You can use it to set a unique custom ID to make it easier to identify the project.

    OPTIONAL PARAMETERS

    When creating a project, you can also add the following common parameters:

    • scanners: Defines the list of all scanners you want to add to the project.
    • members: Defines the list of user IDs for regular projects users.
      Project members can access the project, but are not allowed to change the project configuration.

  2. Run the script.

  3. Analyze the response.
    The following response sample is a simplified version of a successful request, focusing only on the main details relevant to this specific request.

    json
    {
  "config": {
    "packages": [],
    "providers": [
      {
        "enabled": true,
        "id": "providerId",
        "name": "provider"
      }
    ],
    "scanners": [
      {
        "blocking": true,
        "enabled": true,
        "id": "scannerId"
      }
    ]
  },
  "friendlyId": "ADD-FRIENDLY-ID-HERE",
  "id": "projectId",
  "name": "ADD-YOUR-PROJECT-NAME-HERE",
  "type": "app"
}

    The response includes the following key parameters:

    • config > packages: A list of the scanner packages added to the project.
    • config > providers: A list of the providers added to the project.
    • config > scanners: A list of the scanners added to the project.
    • id: The project ID.
    • name: The project name.
    • type: The project type.
    To view the full response, click here.
    json
    {
    "adminCount": 1,
    "adminRoleId": "userId",
    "chatbotId": null,
    "config": {
      "packages": [],
      "providerRouting": null,
      "providers": [
        {
          "default": true,
          "enabled": true,
          "id": "providerId",
          "name": "provider",
          "type": "groq"
        }
      ],
      "scanners": [
        {
          "blocking": true,
          "enabled": true,
          "flagMessage": null,
          "force": false,
          "id": "scannerId"
        }
      ]
    },
    "createdAt": "2025-04-17T11:02:49.730112Z",
    "friendlyId": "ADD-FRIENDLY-ID-HERE",
    "id": "projectId",
    "memberCount": 1,
    "memberRoleId": "roleId",
    "name": "ADD-YOUR-PROJECT-NAME-HERE",
    "orgId": null,
    "type": "app"
}

Add a scanner to a project ​

Our final step in the onboarding journey for Defend is adding a scanner to our new project. In this scenario, we are going to add the first scanner available in the list of scanners.

Scanners can have multiple published versions, with different configurations. So, in addition to adding a scanner to a project, you can also set a specific scanner version as active.

SCANNER VERSIONS

If you don't select a scanner version, the most recently published version is automatically set as active.

To add a scanner:

  1. Edit the following sample.

    python
    from calypsoai import CalypsoAI
from calypsoai.datatypes import ProjectConfigScanner, UUID

# Define the URL and token for CalypsoAI
CALYPSOAI_URL = "https://www.us1.calypsoai.app"
CALYPSOAI_TOKEN = "ADD-YOUR-TOKEN-HERE"

# Initialize the CalypsoAI client
cai = CalypsoAI(url=CALYPSOAI_URL, token=CALYPSOAI_TOKEN)

# Get all scanners
scanners = [scanner for scanner in cai.scanners.iterate()]

# Update the project with the first scanner
cai.projects.update(
    project="ADD-YOUR-PROJECT-ID-HERE",
    scanners=[ProjectConfigScanner(id=scanners[0].id, version="ADD-YOUR-VERSION-ID-HERE", enabled=True)]
)
    • Add your token value.
    • In cai.projects.update > project, provide the ID of your new project.
    • In cai.projects.update > scanners, do the following:
      • In version, provide your scanner version ID.
      • Make sure enabled is set to True.

  2. Run the script.
    If the request is successful, you receive the None response.

    THE NONE RESPONSE

    Confirm the scanner is added to the project by checking the scanner properties in the project.

That's it! Now that you know the Defend basics, you can dive into more advanced operations on our API.
You can also learn the basics of our Inference Red-Team product.

RELATED INFORMATION

Updated at:

CalypsoAI © 2025-present