CalypsoAI

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 stop threats before they reach your applications, for example, blocking prompt injections, jailbreaks, and data exfiltration.

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.

    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.

    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"
}
    • In the first outcome, you can see if any of the scanners flagged the prompt - specific scanner results are listed in the scannerResults object (see below).
      The following values are available:
      • cleared: The prompt was not flagged by the scanners.
      • blocked: Our scanners blocked the prompt or the response to the prompt.
    • In response, you can see the specific response of the default provider.
    • In the scannerResults object, you can see the list of all scans that analyzed your prompt, and additional data related to each scanner.
      • For outcome, the available values are passed and failed.
      • In scanDirection, you can see if the scanner analyzed the request or the response.

        SCANNING DIRECTION

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

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="Project name",
    projectType=ProjectType.APP,
    admins=['userId'],
    providers=[provider.id],
    friendlyId="Friendly-ID-name"
)

# Print the response
print(project.model_dump_json(indent=2))
    • Add your token value.
    • Add values for the following required parameters:
      • 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.

  2. Run the script.

  3. Analyze the response.

    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": "Friendly-ID-name",
    "id": "projectId",
    "memberCount": 1,
    "memberRoleId": "roleId",
    "name": "Project name",
    "orgId": null,
    "type": "app"
}

    You can see all the important details about your new project, for example:

    • The list of providers
    • The list of scanners and their state
    • The date on which the project was created
    • The project name and type

    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.

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 project, provide the ID of your new project.
    • In 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