> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enkryptai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Reference

> Complete reference for dataset, test, and endpoint configurations

This page provides detailed information about all configuration options for the EnkryptAI Red Teaming API V3 payload structure.

<Info>
  To understand what tests are available and their configuration requirements:

  * [Foundation Model Test Catalog](/get-started/redteam/test-catalog) - Tests for foundation models and LLM-based applications
  * [Agent Test Catalog](/get-started/redteam/agent-test-catalog) - Tests for AI agents with tool use and autonomous capabilities
</Info>

## Payload Structure Overview

Every payload consists of four main sections:

```json theme={"system"}
{
    "test_name": "unique_test_identifier",  // Required: Unique identifier for the test run
    "dataset_configuration": {
        // Dataset settings and parameters
    },
    "redteam_test_configurations": {
        // Test settings and parameters
    },
    "endpoint_configuration": {
        // Details of the target model
    }
}
```

<Warning>
  **Required Field**: `test_name` must be included in all payloads and must be unique for each test run. Use descriptive names or UUIDs to ensure uniqueness.
</Warning>

## Top-Level Fields

<ParamField path="test_name" type="string" required>
  A unique identifier for the red team test run. This name is used to identify and track your test execution.

  **Requirements:**

  * Must be unique for each test run
  * Can contain alphanumeric characters, underscores, and hyphens
  * Recommended length: 3-100 characters

  **Examples:**

  * `"my_redteam_test_001"`
  * `"production_model_security_check"`
  * `"redteam_test_2024_01_15"`
  * Using UUID: `f"redteam_test_{str(uuid.uuid4())[:8]}"`

  **Best Practices:**

  * Use descriptive names that indicate the model or purpose
  * Include timestamps or version numbers for tracking
  * Avoid special characters that might cause issues with APIs
</ParamField>

## Dataset Configuration

The dataset configuration specifies settings for generating test prompts when using generated datasets.

### Complete Example

```json theme={"system"}
{
    "dataset_configuration": {
        "system_description": "System description for your AI application",
        "policy_description": "Do not generate any content that is illegal, harmful, or violates the rights of others.",
        "max_prompts": 100,
        "scenarios": 2,
        "categories": 2,
        "depth": 2
    }
}
```

### Field Reference

<ParamField path="system_description" type="string" required>
  Description of the AI system being tested. This helps the attack generator create contextually relevant prompts.

  **Example:** `"This is a customer support chatbot for a banking application"`
</ParamField>

<ParamField path="policy_description" type="string" required>
  The code of conduct or policy that the model should follow. Defines what the model should NOT do.

  **Example:** `"Do not provide harmful or illegal information. Do not share customer data."`
</ParamField>

<ParamField path="max_prompts" type="integer" default="100">
  Maximum number of prompts to generate for the dataset.

  **Range:** 1-1000

  **Guidelines:**

  * Development: 10-50
  * Standard testing: 100-200
  * Comprehensive: 500-1000
</ParamField>

<ParamField path="scenarios" type="integer" default="2">
  Number of different scenarios to test across.

  **Range:** 1-10

  **Description:** Creates variety in attack contexts and use cases.
</ParamField>

<ParamField path="categories" type="integer" default="2">
  Number of risk categories to include in the generated dataset.

  **Range:** 1-15

  **Description:** Spreads testing across different types of risks (toxicity, bias, PII, etc.).
</ParamField>

<ParamField path="depth" type="integer" default="2">
  Depth of the attack tree for generating adversarial prompts.

  **Range:** 1-5

  **Description:** Higher depth creates more sophisticated, multi-step attacks.

  **Guidelines:**

  * Depth 1-2: Simple attacks
  * Depth 3: Moderate complexity
  * Depth 4-5: Complex, multi-layered attacks
</ParamField>

### Usage Notes

<Note>
  The dataset configuration is only used when generating custom datasets. If you're testing with pre-existing prompts, you can omit this section.
</Note>

***

## Red Team Test Configurations

This section specifies which tests to run and how to attack the model for each test type.

### Structure

```json theme={"system"}
{
  "redteam_test_configurations": {
    "test_name": {
      "sample_percentage": 50,
      "attack_methods": {
        // Attack method configuration
      }
    }
  }
}
```

### Common Fields

<ParamField path="sample_percentage" type="integer" required>
  Percentage of the dataset to use for this specific test.

  **Range:** 1-100

  **Guidelines:**

  * Development/Quick Testing: 1-5%
  * Standard Testing: 10-20%
  * Comprehensive Testing: 50-100%

  **Example:** `"sample_percentage": 50` means use 50% of available prompts
</ParamField>

<ParamField path="attack_methods" type="object" required>
  Configuration of attack methods to use for this test. See [Attack Methods Reference](/get-started/redteam/attack-methods-reference) for detailed information.

  **Structure:**

  ```json theme={"system"}
  {
    "basic": {"basic": {"params": {}}},
    "static": {
      "encoding_method": {"params": {...}}
    },
    "dynamic": {
      "iterative_method": {"params": {...}}
    }
  }
  ```
</ParamField>

### Test Categories

<AccordionGroup>
  <Accordion title="Custom Tests (1 test)">
    #### custom\_test

    Custom dataset test for your specific use case.

    **Example:**

    ```json theme={"system"}
    {
      "custom_test": {
        "sample_percentage": 50,
        "attack_methods": {
          "basic": {"basic": {"params": {}}}
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Standard Tests (12 tests)">
    #### bias\_test

    Identifies and exposes biased outputs based on protected attributes (race, gender, age, etc.).

    #### cbrn\_test

    Addresses vulnerabilities related to chemical, biological, radiological, and nuclear domains.

    #### csem\_test

    Addresses vulnerabilities related to child abuse exploitation.

    #### harmful\_test

    Elicits responses that promote harm or danger to individuals or groups.

    #### insecure\_code\_test

    Produces insecure or harmful code snippets with vulnerabilities.

    #### toxicity\_test

    Generates harmful or offensive content including hate speech and profanity.

    #### pii\_test

    Exposes personally identifiable information that should remain private.

    #### copyright\_test

    Exposes copyrighted material that the model should not reproduce.

    #### misinformation\_test

    Tests the model's tendency to generate false or misleading information.

    #### system\_prompt\_extractions\_test

    Attempts to extract the system prompt or instructions.

    #### sponge\_test

    Tests for infinite loops or resource exhaustion attacks.

    #### competitor\_test

    Attempts to extract information about competitors.

    **Example:**

    ```json theme={"system"}
    {
      "bias_test": {
        "sample_percentage": 30,
        "attack_methods": {
          "basic": {"basic": {"params": {}}},
          "static": {"obfuscation": {"params": {}}}
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Agentic Tests (8 tests)">
    Tests specifically designed for AI agents with tool use and autonomous capabilities:

    #### governance\_test

    Testing the alignment and governance of the model including goal misalignment and policy drift.

    #### agent\_output\_quality\_test

    Testing the quality of the agent's output including hallucinations, bias, and toxicity in multi-turn workflows.

    #### tool\_misuse\_test

    Testing the misuse of the model's tools including API integration issues, supply chain vulnerabilities, and resource consumption.

    #### privacy\_test

    Testing privacy protections and data handling including sensitive data exposure and exfiltration channels.

    #### reliability\_and\_observability\_test

    Testing the reliability and observability of agent operations including data poisoning, concept drift, and opaque reasoning.

    #### agent\_behaviour\_test

    Testing the behaviour patterns and decision-making including human manipulation and unsafe actuation.

    #### access\_control\_and\_permissions\_test

    Testing access control and permissions enforcement including credential theft, privilege escalation, and confused deputy attacks.

    #### tool\_extraction\_test

    Test if the agent tool information can be extracted in outputs.

    **Example:**

    ```json theme={"system"}
    {
      "tool_misuse_test": {
        "sample_percentage": 20,
        "attack_methods": {
          "basic": {"basic": {"params": {}}},
          "dynamic": {"multi_turn": {"params": {}}}
        }
      },
      "access_control_and_permissions_test": {
        "sample_percentage": 25,
        "attack_methods": {
          "basic": {"basic": {"params": {}}},
          "static": {"obfuscation": {"params": {}}}
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Specialized Tests for Generated Datasets (8 tests)">
    Advanced tests that require generated adversarial datasets:

    #### adv\_bias\_test

    Uncover biased outputs through adversarial methods.

    #### adv\_info\_test

    Extract sensitive or unintended information from a generated dataset.

    #### adv\_persona\_test

    Adversarial persona manipulation and identity spoofing attacks.

    #### adv\_command\_test

    Manipulate the model to execute unintended commands.

    #### adv\_pii\_test

    Expose personally identifiable information through adversarial techniques.

    #### adv\_competitor\_test

    Exploit vulnerabilities to gain an advantage over competitors.

    #### adv\_sponge\_test

    Advanced resource exhaustion and denial of service attacks.

    #### adv\_persona\_test

    Adversarial persona manipulation and identity spoofing attacks.

    **Example:**

    ```json theme={"system"}
    {
      "adv_bias_test": {
        "sample_percentage": 50,
        "attack_methods": {
          "basic": {"basic": {"params": {}}},
          "static": {
            "base64_encoding": {
              "params": {"encoding_type": "base64", "iterations": 2}
            }
          }
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Multiple Tests Example

You can run multiple tests in a single payload:

```json theme={"system"}
{
  "redteam_test_configurations": {
    "bias_test": {
      "sample_percentage": 30,
      "attack_methods": {
        "basic": {"basic": {"params": {}}}
      }
    },
    "harmful_test": {
      "sample_percentage": 50,
      "attack_methods": {
        "basic": {"basic": {"params": {}}},
        "static": {"obfuscation": {"params": {}}}
      }
    },
    "pii_test": {
      "sample_percentage": 20,
      "attack_methods": {
        "basic": {"basic": {"params": {}}}
      }
    }
  }
}
```

***

## Endpoint Configuration

This section provides specifics about the model to be tested.

### Complete Example

```json theme={"system"}
{
    "endpoint_configuration": {
        "testing_for": "foundationModels",
        "model_name": "gpt-4o",
        "model_config": {
            "model_provider": "openai",
            "endpoint": {
                "scheme": "https",
                "host": "api.openai.com",
                "port": 443,
                "base_path": "/v1/chat/completions"
            },
            "auth_data": {
                "header_name": "Authorization",
                "header_prefix": "Bearer",
                "space_after_prefix": true
            },
            "apikeys": ["OPENAI_API_KEY"],
            "input_modalities": ["text"],
            "output_modalities": ["text"]
        }
    }
}
```

### Top-Level Fields

<ParamField path="testing_for" type="string" required>
  Identifies the AI system type being tested.

  **Options:**

  * `"foundationModels"` - Base language models (GPT, Claude, Gemini, etc.)
  * `"chatbotsAndCopilots"` - Chat interfaces and coding assistants
  * `"agents"` - Autonomous AI agents with tool use
  * `"URL"` - Custom API endpoints
</ParamField>

<ParamField path="model_name" type="string" required>
  The name or identifier for the model.

  **Examples:**

  * `"gpt-4o"`
  * `"gpt-4o-mini"`
  * `"claude-3-5-sonnet-20241022"`
  * `"google/gemma-7b-it"`
</ParamField>

<ParamField path="model_config" type="object" required>
  Configuration object for the model endpoint. See detailed fields below.
</ParamField>

### Model Config Fields

<ParamField path="model_provider" type="string" required>
  The provider of the model.

  **Supported Providers:**

  * `"openai"` - OpenAI models
  * `"anthropic"` - Anthropic models
  * `"together"` - Together AI
  * `"groq"` - Groq
  * `"google"` - Google (Gemini)
  * `"aws_bedrock"` - AWS Bedrock
  * `"azure"` - Azure OpenAI
  * `"huggingface"` - HuggingFace models

  For complete list, see [GET Defaults API](/api-reference/models-api-reference/endpoint/get-defaults).
</ParamField>

<ParamField path="endpoint" type="object" required>
  Object containing endpoint details.

  **Subfields:**

  * `scheme` (string): Protocol scheme (e.g., `"https"`)
  * `host` (string): API host (e.g., `"api.openai.com"`)
  * `port` (integer): Port number (e.g., `443`)
  * `base_path` (string): Base path for API endpoint (e.g., `"/v1/chat/completions"`)
</ParamField>

<ParamField path="auth_data" type="object" required>
  Authentication configuration. Format varies by provider.

  **Standard Header Auth (most providers):**

  ```json theme={"system"}
  {
    "header_name": "Authorization",
    "header_prefix": "Bearer",
    "space_after_prefix": true
  }
  ```

  **AWS Bedrock:**

  ```json theme={"system"}
  {
    "aws_access_key_id": "YOUR_ACCESS_KEY",
    "aws_secret_access_key": "YOUR_SECRET_KEY"
  }
  ```

  **Google Gemini (Query Param):**

  ```json theme={"system"}
  {
    "param_name": "key"
  }
  ```
</ParamField>

<ParamField path="apikeys" type="array" required>
  Array of API keys for authentication.

  **Example:** `["OPENAI_API_KEY"]`

  **Note:** Can provide multiple keys for load balancing.
</ParamField>

<ParamField path="input_modalities" type="array" required>
  Input types the model accepts.

  **Options:**

  * `["text"]` - Text-only (LLMs)
  * `["text", "image"]` - Text and images (VLMs)
  * `["text", "audio"]` - Text and audio (ALMs)
</ParamField>

<ParamField path="output_modalities" type="array" required>
  Output types the model produces.

  **Typical:** `["text"]`
</ParamField>

<ParamField path="system_prompt" type="string">
  Optional. Sets initial model behavior or instructions.

  **Example:** `"You are a helpful customer support assistant."`
</ParamField>

<ParamField path="rate_per_min" type="integer">
  Optional. Rate limit for API calls per minute.

  **Example:** `60`
</ParamField>

<ParamField path="paths" type="object">
  Optional. Object defining API path mappings.

  **Example:**

  ```json theme={"system"}
  {
    "completions": "/completions",
    "chat": "/chat/completions"
  }
  ```
</ParamField>

<ParamField path="metadata" type="object">
  Optional. Provider-specific configuration options.

  **Azure OpenAI:**

  ```json theme={"system"}
  {
    "azure_instance": "your-instance",
    "azure_api_version": "2023-05-15",
    "azure_deployment_id": "your-deployment"
  }
  ```

  **AWS Bedrock:**

  ```json theme={"system"}
  {
    "bedrock.aws_region": "us-east-1"
  }
  ```

  **Anthropic:**

  ```json theme={"system"}
  {
    "anthropic_version": "2023-06-01"
  }
  ```

  **HuggingFace:**

  ```json theme={"system"}
  {
    "huggingface.use_cache": true,
    "huggingface.wait_for_model": true
  }
  ```
</ParamField>

### Model-Type Specific Examples

<CodeGroup>
  ```json LLM (Text-to-Text) theme={"system"}
  {
    "endpoint_configuration": {
      "testing_for": "foundationModels",
      "model_name": "gpt-4o-mini",
      "model_config": {
        "model_provider": "openai",
        "endpoint": {
          "scheme": "https",
          "host": "api.openai.com",
          "port": 443,
          "base_path": "/v1/chat/completions"
        },
        "auth_data": {
          "header_name": "Authorization",
          "header_prefix": "Bearer",
          "space_after_prefix": true
        },
        "apikeys": ["OPENAI_API_KEY"],
        "input_modalities": ["text"],
        "output_modalities": ["text"]
      }
    }
  }
  ```

  ```json VLM (Text+Image-to-Text) theme={"system"}
  {
    "endpoint_configuration": {
      "testing_for": "foundationModels",
      "model_name": "gpt-4o",
      "model_config": {
        "model_provider": "openai",
        "endpoint": {
          "scheme": "https",
          "host": "api.openai.com",
          "port": 443,
          "base_path": "/v1/chat/completions"
        },
        "auth_data": {
          "header_name": "Authorization",
          "header_prefix": "Bearer",
          "space_after_prefix": true
        },
        "apikeys": ["OPENAI_API_KEY"],
        "input_modalities": ["text", "image"],
        "output_modalities": ["text"]
      }
    }
  }
  ```

  ```json ALM (Text+Audio-to-Text) theme={"system"}
  {
    "endpoint_configuration": {
      "testing_for": "foundationModels",
      "model_name": "whisper-1",
      "model_config": {
        "model_provider": "openai",
        "endpoint": {
          "scheme": "https",
          "host": "api.openai.com",
          "port": 443,
          "base_path": "/v1/audio/transcriptions"
        },
        "auth_data": {
          "header_name": "Authorization",
          "header_prefix": "Bearer",
          "space_after_prefix": true
        },
        "apikeys": ["OPENAI_API_KEY"],
        "input_modalities": ["text", "audio"],
        "output_modalities": ["text"]
      }
    }
  }
  ```

  ```json Azure OpenAI theme={"system"}
  {
    "endpoint_configuration": {
      "testing_for": "foundationModels",
      "model_name": "gpt-4",
      "model_config": {
        "model_provider": "azure",
        "endpoint": {
          "scheme": "https",
          "host": "your-instance.openai.azure.com",
          "port": 443,
          "base_path": "/openai/deployments/your-deployment/chat/completions"
        },
        "auth_data": {
          "header_name": "api-key",
          "header_prefix": "",
          "space_after_prefix": false
        },
        "apikeys": ["AZURE_OPENAI_KEY"],
        "metadata": {
          "azure_instance": "your-instance",
          "azure_api_version": "2023-05-15",
          "azure_deployment_id": "your-deployment"
        },
        "input_modalities": ["text"],
        "output_modalities": ["text"]
      }
    }
  }
  ```
</CodeGroup>

### Provider-Specific Notes

<CardGroup cols={2}>
  <Card title="OpenAI" icon="openai">
    Standard bearer authentication with `Authorization: Bearer YOUR_KEY`
  </Card>

  <Card title="Anthropic" icon="message">
    Requires `anthropic_version` in metadata and `x-api-key` header
  </Card>

  <Card title="AWS Bedrock" icon="aws">
    Uses AWS credentials instead of API keys. Requires region in metadata.
  </Card>

  <Card title="Google Gemini" icon="google">
    Uses query parameter authentication with `?key=YOUR_KEY`
  </Card>

  <Card title="Azure OpenAI" icon="microsoft">
    Requires Azure-specific metadata including instance and deployment ID
  </Card>

  <Card title="HuggingFace" icon="face-smile">
    Supports caching and wait-for-model options in metadata
  </Card>
</CardGroup>

## Best Practices

<Warning>
  **Security Best Practices:**

  * Never commit API keys to version control
  * Use environment variables for sensitive credentials
  * Rotate API keys regularly
  * Use separate keys for testing vs production
</Warning>

<Tip>
  **Configuration Tips:**

  * Start with `sample_percentage` of 2-5% for initial testing
  * Gradually increase to 50-100% for comprehensive assessments
  * Use multiple test types to cover different risk categories
  * Match attack methods to your specific security concerns
</Tip>

## Related Pages

* [Payload Guide](/get-started/redteam/payload-guide) - Overview and quick reference
* [Test Catalogs](/get-started/redteam/test-catalog) - Comprehensive test catalogs for foundation models and agents
* [Attack Methods Reference](/get-started/redteam/attack-methods-reference) - Detailed attack method information
* [Examples](/get-started/redteam/examples) - Complete payload examples
* [GET Defaults API](/api-reference/models-api-reference/endpoint/get-defaults) - Supported providers and models