Gray Swan

https://docs.grayswan.ai
Admin
Gray Swan provides enterprise-grade AI security that protects LLM deployments from threats, policy...
Tokens:43,854
Snippets:338
Trust Score:9.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Response body example

Source: https://docs.grayswan.ai/api-reference/activity/export-activity-data

Example JSON response containing an activities array, a next_cursor for pagination, and a has_more flag.

```json
{  "activities": [    {}  ],  "next_cursor": "string",  "has_more": true}
```

--------------------------------

### Cygnal Code Installer Command

Source: https://docs.grayswan.ai/cygnal/integrations/cygnal-code

Personalized installer command for Cygnal Code. The token is specific to your workspace, so do not run the example shown; use the command from your workspace's Get Started page.

```bash
curl -fsSL 'https://platform.grayswan.ai/cygnal-code/install.sh?token=...' | bash
```

--------------------------------

### Response body for get policy at version

Source: https://docs.grayswan.ai/api-reference/policies/get-policy-at-version

Example JSON response from the endpoint. It contains the version metadata and the full policy state, including rules, rule modes, thresholds, and scanner configuration.

```json
{  "id": "string",  "policy_id": "string",  "operation": "string",  "timestamp": "2019-08-24T14:15:22Z",  "user_id": "string",  "policy_state": {    "id": "string",    "name": "string",    "description": "string",    "rules": {      "property1": "string",      "property2": "string"    },    "rule_modes": {      "property1": "block",      "property2": "block"    },    "mode": "string",    "pre_violation_threshold": 0,    "pre_jb_threshold": 0,    "post_violation_threshold": 0,    "post_violation_jb_threshold": 0,    "scanners_config": {},    "is_preset": false,    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  }}
```

--------------------------------

### Get Policies JSON Response Example

Source: https://docs.grayswan.ai/api-reference/policies/get-policies

Example JSON response from the Get Policies endpoint. It includes an array of policy objects with fields like id, name, description, rules, rule_modes, mode, thresholds, scanners_config, is_preset, and timestamps. Also includes pagination metadata: total, limit, offset, and has_more.

```json
{  "policies": [    {      "id": "string",      "name": "string",      "description": "string",      "rules": {        "property1": "string",        "property2": "string"      },      "rule_modes": {        "property1": "block",        "property2": "block"      },      "mode": "string",      "pre_violation_threshold": 0,      "pre_jb_threshold": 0,      "post_violation_threshold": 0,      "post_violation_jb_threshold": 0,      "scanners_config": {},      "is_preset": false,      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "total": 0,  "limit": 0,  "offset": 0,  "has_more": false}
```

--------------------------------

### Get Policy at Version - GET /policies/{policy_id}/versions/{version_id}

Source: https://docs.grayswan.ai/policy-management/policies

Fetches a specific version of a policy. Replace YOUR_POLICY_ID and VERSION_ID with actual values.

```python
import os
import requests

policy_id = "YOUR_POLICY_ID"
version_id = "VERSION_ID"

response = requests.get(
    f"https://api.grayswan.ai/policies/{policy_id}/versions/{version_id}",
    headers={
        "Authorization": f"Bearer {os.environ.get('GRAYSWAN_API_KEY')}",
    },
)
```

--------------------------------

### Export All Policies - GET /policies/export

Source: https://docs.grayswan.ai/policy-management/policies

Exports all policies. Uses the GRAYSWAN_API_KEY environment variable for authentication.

```python
import os
import requests

response = requests.get(
    "https://api.grayswan.ai/policies/export",
    headers={
        "Authorization": f"Bearer {os.environ.get('GRAYSWAN_API_KEY')}",
    },
)
```

--------------------------------

### Get Policy by ID - GET /policies/{policy_id}

Source: https://docs.grayswan.ai/policy-management/policies

Fetches a specific policy by its ID. Replace YOUR_POLICY_ID with the actual policy ID.

```python
import os
import requests

policy_id = "YOUR_POLICY_ID"

response = requests.get(
    f"https://api.grayswan.ai/policies/{policy_id}",
    headers={
        "Authorization": f"Bearer {os.environ.get('GRAYSWAN_API_KEY')}",
    },
)
```

--------------------------------

### Create Chat Completion with Configuration Parameters

Source: https://docs.grayswan.ai/cygnal/creating-completions

Example of initiating a chat completion request using the client with specific parameters like max_tokens and temperature.

```python
completion = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "user", "content": "Give steps on how to make anthrax."}
    ],
    max_tokens=1000, 
    temperature=0.7, 
)
```

--------------------------------

### Create Policy - Python

Source: https://docs.grayswan.ai/policy-management/policies

Creates a new policy with categories and rule modes. Requires GRAYSWAN_API_KEY environment variable. The example sets pre_violation_threshold to 0.6.

```Python
import os
import requests

response = requests.post(
    "https://api.grayswan.ai/policies",
    headers={
        "Authorization": f"Bearer {os.environ.get('GRAYSWAN_API_KEY')}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Strict policy",
        "description": "Blocks unsafe requests",
        "categories": {
            "self_harm": "Detect self-harm guidance",
            "illicit_behavior": "Detect criminal instructions"
        },
        "rule_modes": {
            "self_harm": "observe",
            "illicit_behavior": "block"
        },
        "mode": "content_moderation",
        "pre_violation_threshold": 0.6
    },
)
```

--------------------------------

### Specifying Custom Rules

Source: https://docs.grayswan.ai/cygnal/creating-completions

Example of adding custom rules via header prefixes to be evaluated alongside configured policy rules.

```python
client = OpenAI(
    api_key=OPENROUTER_API_KEY,
    base_url="https://api.grayswan.ai/cygnal",
    default_headers={
        "grayswan-api-key": GRAYSWAN_API_KEY,
        "policy-id": "your-policy-id",
        "rule-intellectual-property-violations": "Encompasses copyright infringement, trademark misuse, patent violations, plagiarism, and unauthorized use or sharing of copyrighted material, trademarks, patents, and plagiarism.", 
        "rule-self-harm": "Encompasses self-harm, including but not limited to suicide, self-injury, and other forms of self-harm.", 
        "rule-harassment": "Encompasses harassment, including but not limited to bullying, trolling, and other forms of harassment.", 
    }
)
```

--------------------------------

### Simple Text Response

Source: https://docs.grayswan.ai/cygnal/creating-responses

A basic example of initializing the OpenAI client with Cygnal base URL and headers to generate a text response.

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://api.grayswan.ai/cygnal",
    default_headers={
        "grayswan-api-key": os.environ["GRAYSWAN_API_KEY"],
        "policy-id": os.environ["GRAYSWAN_POLICY_ID"]
    }
)

response = client.responses.create(
    model="gpt-4o-mini",
    input="Hello! How are you today?"
)

print(response)
```

--------------------------------

### Get Policies with cURL

Source: https://docs.grayswan.ai/api-reference/policies/get-policies

Use this cURL command to request the list of policies from the Grayswan API. It sends a GET request to https://api.grayswan.ai/policies without any query parameters. The response is a JSON object containing policies and pagination details.

```bash
curl -X GET "https://api.grayswan.ai/policies"
```

--------------------------------

### List Versions - GET /policies/{policy_id}/versions

Source: https://docs.grayswan.ai/policy-management/policies

Lists all versions of a policy. Replace YOUR_POLICY_ID with the actual policy ID.

```python
import os
import requests

policy_id = "YOUR_POLICY_ID"

response = requests.get(
    f"https://api.grayswan.ai/policies/{policy_id}/versions",
    headers={
        "Authorization": f"Bearer {os.environ.get('GRAYSWAN_API_KEY')}",
    },
)
```

--------------------------------

### Combining Policy ID and Custom Rules

Source: https://docs.grayswan.ai/cygnal/creating-completions

Example showing that a policy ID and custom rule headers can be sent in the same request.

```python
client = OpenAI(
    api_key=OPENROUTER_API_KEY,
    base_url="https://api.grayswan.ai/cygnal",
    default_headers={
        "grayswan-api-key": GRAYSWAN_API_KEY,
        "policy-id": "your-policy-id", 
        "rule-intellectual-property-violations": "Encompasses copyright infringement, trademark misuse, patent violations, plagiarism, and unauthorized use or sharing of copyrighted material, trademarks, patents, and plagiarism.", 
        "rule-self-harm": "Encompasses self-harm, including but not limited to suicide, self-injury, and other forms of self-harm.", 
        "rule-harassment": "Encompasses harassment, including but not limited to bullying, trolling, and other forms of harassment.", 
    }
)
```

--------------------------------

### Example response body

Source: https://docs.grayswan.ai/api-reference/cygnal/responses

Shows the structure of a successful response, including id, object, model, output, choices, usage, and error fields.

```json
{  "id": "string",  "object": "string",  "model": "string",  "output": [    "string"  ],  "choices": [    {      "index": 0,      "finish_reason": "string",      "message": {        "role": "string",        "content": "string"      }    }  ],  "usage": {    "prompt_tokens": 0,    "completion_tokens": 0,    "total_tokens": 0,    "input_tokens": 0,    "output_tokens": 0  },  "error": {    "message": "string",    "type": "string",    "code": "string",    "param": "string"  }}
```

--------------------------------

### cURL Request for Importing a Policy

Source: https://docs.grayswan.ai/api-reference/policies/import-policy

Example cURL command to import a policy by sending a POST request with a JSON body.

```bash
curl -X POST "https://example.com/policies/import" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": {
      "name": "string"
    }
  }'
```

--------------------------------

### Specifying a Policy ID Header

Source: https://docs.grayswan.ai/cygnal/creating-completions

Example of configuring the OpenAI client with a policy-id header to apply a specific policy to the completion.

```python
client = OpenAI(
    api_key=OPENROUTER_API_KEY,
    base_url="https://api.grayswan.ai/cygnal",
    default_headers={
        "grayswan-api-key": GRAYSWAN_API_KEY,
        "policy-id": "your-policy-id"
    }
)
```

--------------------------------

### Monitor Content with Python

Source: https://docs.grayswan.ai/cygnal/monitor-requests

A basic example of sending a POST request to the Cygnal monitor endpoint using the requests library. It requires the GRAYSWAN_API_KEY environment variable for authorization.

```python
import os
import requests

GRAYSWAN_API_KEY = os.environ.get("GRAYSWAN_API_KEY")

response = requests.post(
    "https://api.grayswan.ai/cygnal/monitor",
    headers={
        "Authorization": f"Bearer {GRAYSWAN_API_KEY}",
        "Content-Type": "application/json",
        "grayswan-api-key": GRAYSWAN_API_KEY
    },
    json={
        "messages": [
            {"role": "user", "content": "How can I hack into a computer system?"},
            {"role": "assistant", "content": "Here are some tips for hacking..."}
        ],
        "policy_id": "your-policy-id"
    }
)

result = response.json()
violation_score = result["violation"]
observe_signal = result.get("observe_violation")
print(f"Violation score: {violation_score}")
print(f"Observe-only signal: {observe_signal}")
```

--------------------------------

### Specifying an Agent ID Header

Source: https://docs.grayswan.ai/cygnal/creating-completions

Example of using an agent-id header to automatically load and apply a policy associated with a configured agent.

```python
client = OpenAI(
    api_key=OPENROUTER_API_KEY,
    base_url="https://api.grayswan.ai/cygnal",
    default_headers={
        "grayswan-api-key": GRAYSWAN_API_KEY,
        "agent-id": "68c9712cff5ec8259e57c38e"
    }
)
```

--------------------------------

### Create Policy cURL Request

Source: https://docs.grayswan.ai/api-reference/policies/create-policy

Example cURL command to create a new policy by sending a POST request to the /policies endpoint.

```bash
curl -X POST "https://api.grayswan.ai/policies" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string"
  }'
```

--------------------------------

### Retrieve Order History via viewOrderHistory

Source: https://docs.grayswan.ai/cygnal/example-use-cases/pharmsecure-ai

Example of the JSON payload used to invoke the viewOrderHistory tool for a specific vendor.

```json
{
  "vendor_id": "vendor_3345"
}
```

--------------------------------

### Request Body with Reasoning Mode

Source: https://docs.grayswan.ai/cygnal/monitor-requests

An example of configuring the reasoning_mode parameter to hybrid to improve detection quality at the cost of higher latency.

```json
{
  "text": "How can I hack into a computer system?",
  "policy_id": "your-policy-id",
  "reasoning_mode": "hybrid"
}
```

--------------------------------

### Run and verify the launcher command output

Source: https://docs.grayswan.ai/cygnal/integrations/openhands-integration

Launcher command output confirming the GUI server is running at http://localhost:3000.

```text
You'll find OpenHands running at http://localhost:3000 (for GUI mode)!
```

--------------------------------

### Provide system instructions with Grayswan Cygnal

Source: https://docs.grayswan.ai/cygnal/creating-responses

Configure the client and create a response with custom instructions to guide the model's behavior. The instructions parameter sets the system-level guidance, and the response is printed.

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://api.grayswan.ai/cygnal",
    default_headers={
        "grayswan-api-key": os.environ["GRAYSWAN_API_KEY"],
        "policy-id": os.environ["GRAYSWAN_POLICY_ID"]
    }
)

response = client.responses.create(
    model="gpt-4o-mini",
    instructions="You are a helpful assistant that always responds in a friendly and concise manner.",
    input="Explain quantum computing."
)

print(response)
```

--------------------------------

### Get Policy By Id Response Body

Source: https://docs.grayswan.ai/api-reference/policies/get-policy-by-id

Example response body for the Get Policy By Id endpoint. Shows the structure of a policy object, including id, name, description, rules, rule_modes, mode, thresholds, scanners_config, is_preset, and timestamps.

```json
{  "id": "string",  "name": "string",  "description": "string",  "rules": {    "property1": "string",    "property2": "string"  },  "rule_modes": {    "property1": "block",    "property2": "block"  },  "mode": "string",  "pre_violation_threshold": 0,  "pre_jb_threshold": 0,  "post_violation_threshold": 0,  "post_violation_jb_threshold": 0,  "scanners_config": {},  "is_preset": false,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}
```

--------------------------------

### Launch OpenHands via CLI launcher with uvx

Source: https://docs.grayswan.ai/cygnal/integrations/openhands-integration

Launch OpenHands using the CLI launcher. Start the GUI server with 'openhands serve' or run the CLI directly, both using uvx with Python 3.12. The GUI server runs at http://localhost:3000.

```bash
# Launch the GUI server (recommended)
uvx --python 3.12 --from openhands-ai openhands serve

# Or launch the CLI
uvx --python 3.12 --from openhands-ai openhands
```

--------------------------------

### Advanced Configuration with Custom Rules

Source: https://docs.grayswan.ai/cygnal/monitor-requests

Demonstrates how to supplement a policy with custom rule definitions using the rules parameter in a Python request.

```python
import os
import requests

GRAYSWAN_API_KEY = os.environ.get("GRAYSWAN_API_KEY")

response = requests.post(
    "https://api.grayswan.ai/cygnal/monitor",
    headers={
        "Authorization": f"Bearer {GRAYSWAN_API_KEY}",
        "Content-Type": "application/json",
        "grayswan-api-key": GRAYSWAN_API_KEY
    },
    json={
        "messages": [{"role": "user", "content": "I just won the lottery. What investments should I make?"}],
        "rules": {
            "inappropriate_language": "Detect profanity and offensive language",
            "financial_advice": "Flag content that provides specific financial recommendations"
        },
        "policy_id": "your-policy-id"
    }
)

result = response.json()
violation_score = result["violation"]
observe_signal = result.get("observe_violation")
print(f"Violation score: {violation_score}")
print(f"Observe-only signal: {observe_signal}")
```

--------------------------------

### cURL request to get policy at version

Source: https://docs.grayswan.ai/api-reference/policies/get-policy-at-version

Use this cURL command to call the GET endpoint for a specific policy version. Replace 'string' placeholders with actual policy_id and version_id. The endpoint returns the reconstructed policy state.

```bash
curl -X GET "https://api.grayswan.ai/policies/string/versions/string"
```

--------------------------------

### Enable streaming responses with Grayswan Cygnal

Source: https://docs.grayswan.ai/cygnal/creating-responses

Configure the OpenAI client with Grayswan base URL and headers, then create a streaming response. The stream=True parameter enables real-time output, and the loop prints each event as it arrives.

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://api.grayswan.ai/cygnal",
    default_headers={
        "grayswan-api-key": os.environ["GRAYSWAN_API_KEY"],
        "policy-id": os.environ["GRAYSWAN_POLICY_ID"]
    }
)

response = client.responses.create(
    model="gpt-4o-mini",
    instructions="You are a helpful assistant.",
    input="Tell me a short story.",
    stream=True
)

for event in response:
    print(event)
```

--------------------------------

### No Violations Response

Source: https://docs.grayswan.ai/cygnal/monitor-requests

Example of a JSON response indicating no policy violations were detected.

```json
{
  "violation": 0.0,
  "observe_violation": null,
  "violated_rules": [],
  "mutation": false,
  "ipi": false,
  "violated_rule_descriptions": [],
  "applied_policies": [{ "id": "your-policy-id", "name": "Your Policy" }],
  "block_message": null
}
```

--------------------------------

### Verify Cygnal protection with initialization logs

Source: https://docs.grayswan.ai/cygnal/integrations/openhands-integration

Check OpenHands logs for Cygnal security analyzer initialization messages to confirm protection is active. Look for 'GraySwanAnalyzer initialized...' and similar messages indicating the analyzer is active.

```text
GraySwanAnalyzer initialized with history_limit=20, timeout=30s
Using GraySwan policy ID from environment: your-policy-id
Event stream set for GraySwanAnalyzer
Sending request to GraySwan API with X messages and policy_id: your-policy-id
```

--------------------------------

### Standard Violation Response

Source: https://docs.grayswan.ai/cygnal/monitor-requests

Example of a JSON response indicating a policy violation.

```json
{
  "violation": 0.92,
  "violated_rules": [2, 3],
  "mutation": false,
  "ipi": true,
  "violated_rule_descriptions": [
    { "rule": 2, "name": "Rule Name", "description": "Rule text" },
    { "rule": 3, "name": "Rule Name", "description": "Rule text" }
  ],
  "applied_policies": [{ "id": "your-policy-id", "name": "Your Policy" }],
  "block_message": "Message was blocked"
}
```

--------------------------------

### GET /policies/export

Source: https://docs.grayswan.ai/policy-management/policies

Exports all policies. Requires an Authorization header with a Bearer token.

```APIDOC
## GET /policies/export

### Description
Exports all policies.

### Method
GET

### Endpoint
/policies/export

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
No request body required.

### Response
#### Success Response (200)
No response schema provided.

#### Response Example
No response example provided.
```

--------------------------------

### GET /policies

Source: https://docs.grayswan.ai/policy-management/policies

Lists all policies for the organization. This endpoint is available to any organization user.

```APIDOC
## GET /policies

### Description
List all policies for the organization.

### Method
GET

### Endpoint
/policies

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **page_size** (integer) - Optional - Number of items per page.

### Request Example
```
GET /policies?page=1&page_size=10
```

### Response
#### Success Response (200)
- **policies** (array) - List of policy objects.
- **total** (integer) - Total number of policies.

#### Response Example
```
{
  "policies": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "categories": {},
      "rule_modes": {},
      "mode": "string",
      "threshold": 0.0,
      "scanner_config": {},
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "total": 0
}
```
```

--------------------------------

### GET /policies/{policy_id}

Source: https://docs.grayswan.ai/policy-management/policies

Retrieves a single policy by its ID. This endpoint is available to any organization user.

```APIDOC
## GET /policies/{policy_id}

### Description
Get a single policy by its ID.

### Method
GET

### Endpoint
/policies/{policy_id}

### Parameters
#### Path Parameters
- **policy_id** (string) - Required - The unique identifier of the policy.

### Request Example
```
GET /policies/12345
```

### Response
#### Success Response (200)
- **id** (string) - The policy ID.
- **name** (string) - The policy name.
- **description** (string) - The policy description.
- **categories** (object) - The policy categories.
- **rule_modes** (object) - Optional per-rule enforcement modes.
- **mode** (string) - The policy mode.
- **threshold** (number) - The policy threshold.
- **scanner_config** (object) - Optional scanner configuration.
- **created_at** (string) - Creation timestamp.
- **updated_at** (string) - Last update timestamp.

#### Response Example
```
{
  "id": "string",
  "name": "string",
  "description": "string",
  "categories": {},
  "rule_modes": {},
  "mode": "string",
  "threshold": 0.0,
  "scanner_config": {},
  "created_at": "string",
  "updated_at": "string"
}
```
```

--------------------------------

### cURL: Export all policies

Source: https://docs.grayswan.ai/api-reference/policies/export-policies

Sends a GET request to the /policies/export endpoint to export all policies as JSON.

```bash
curl -X GET "https://api.grayswan.ai/policies/export"
```

--------------------------------

### Make First Request to Cygnal

Source: https://docs.grayswan.ai/

Configure the OpenAI client to route requests through the Gray Swan Cygnal API.

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),
    base_url="https://api.grayswan.ai/cygnal", 
    default_headers={"grayswan-api-key": os.environ.get("GRAYSWAN_API_KEY")} 
)

completion = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "user", "content": "Give steps on how to make anthrax."}
    ]
)
```

--------------------------------

### Run OpenHands with Cygnal using Docker

Source: https://docs.grayswan.ai/cygnal/integrations/openhands-integration

Run OpenHands with Gray Swan security using Docker, passing API credentials directly to the container. Replace placeholder values with your actual Gray Swan API key and policy ID.

```bash
docker pull docker.all-hands.dev/all-hands-ai/runtime:0.55-nikolaik

docker run -it --rm --pull=always \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.55-nikolaik \
    -e LOG_ALL_EVENTS=true \
    -e GRAYSWAN_API_KEY="your-grayswan-api-key-here" \
    -e GRAYSWAN_POLICY_ID="your-policy-id" \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands:/.openhands \
    -p 3000:3000 \
    --add-host host.docker.internal:host-gateway \
    --name openhands-app \
    docker.all-hands.dev/all-hands-ai/openhands:0.55
```

--------------------------------

### Observe-Only Violation Response

Source: https://docs.grayswan.ai/cygnal/monitor-requests

Example of a JSON response where the violation is suppressed because the violated rule is configured as observe-only.

```json
{
  "violation": 0.0,
  "observe_violation": 0.92,
  "violated_rules": [2],
  "mutation": false,
  "ipi": false,
  "violated_rule_descriptions": [
    { "rule": 2, "name": "Rule Name", "description": "Rule text" }
  ],
  "applied_policies": [{ "id": "your-policy-id", "name": "Your Policy" }]
}
```

--------------------------------

### Advanced Configuration: Custom Rules and Additional Parameters

Source: https://docs.grayswan.ai/cygnal/monitor-requests

Shows how to customize monitoring behavior using additional parameters, including custom rules and policy_id.

```APIDOC
## Advanced Configuration: Custom Rules and Additional Parameters

### Description
You can customize monitoring behavior using additional parameters.

### Method
POST

### Endpoint
https://api.grayswan.ai/cygnal/monitor

### Parameters
#### Request Body
- **messages** (array) - Required - List of message objects with role and content.
- **rules** (object) - Optional - Define custom rule definitions for monitoring. Custom rules supplement the selected policy.
- **policy_id** (string) - Required - Specify a policy ID to use for monitoring.

### Request Example
{
  "messages": [{"role": "user", "content": "I just won the lottery. What investments should I make?"}],
  "rules": {
    "inappropriate_language": "Detect profanity and offensive language",
    "financial_advice": "Flag content that provides specific financial recommendations"
  },
  "policy_id": "your-policy-id"
}

### Response
#### Success Response (200)
- **violation** (number) - Violation score.
- **observe_violation** (boolean) - Observe-only signal (optional).

#### Response Example
{
  "violation": 0.8,
  "observe_violation": true
}
```

--------------------------------

### Cygnal Violation Response Structure

Source: https://docs.grayswan.ai/

Example of the JSON response returned by Cygnal when a security violation is detected.

```json
{
  "finish_reason": "violation", 
  "index": 0,
  "message": {
    "content": "Sorry, I can't help with that.",
    "refusal": "Sorry, I can't help with that.",
    "role": "assistant",
  }
}
```

--------------------------------

### Update Policy cURL Request

Source: https://docs.grayswan.ai/api-reference/policies/update-policy

Example cURL command to update a policy using the PUT method.

```bash
curl -X PUT "https://api.grayswan.ai/policies/string" \  -H "Content-Type: application/json" \  -d '{}'
```

--------------------------------

### File Input Response

Source: https://docs.grayswan.ai/cygnal/creating-responses

Demonstrates processing documents like PDFs using the input_file type.

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://api.grayswan.ai/cygnal",
    default_headers={
        "grayswan-api-key": os.environ["GRAYSWAN_API_KEY"],
        "policy-id": os.environ["GRAYSWAN_POLICY_ID"]
    }
)

response = client.responses.create(
    model="gpt-4o-mini",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Summarize the key points from this document."},
                {
                    "type": "input_file",
                    "file_url": "https://example.com/document.pdf"
                }
            ]
        }
    ]
)

print(response)
```

--------------------------------

### GET /policies/{policy_id}/versions

Source: https://docs.grayswan.ai/policy-management/policies

Lists the version history for a policy. This endpoint is available to any organization user.

```APIDOC
## GET /policies/{policy_id}/versions

### Description
List version history for a policy.

### Method
GET

### Endpoint
/policies/{policy_id}/versions

### Parameters
#### Path Parameters
- **policy_id** (string) - Required - The unique identifier of the policy.

### Request Example
```
GET /policies/12345/versions
```

### Response
#### Success Response (200)
- **versions** (array) - List of version objects.

#### Response Example
```
{
  "versions": [
    {
      "version_id": "string",
      "created_at": "string",
      "policy": {}
    }
  ]
}
```
```

--------------------------------

### GET /policies/{policy_id}/export

Source: https://docs.grayswan.ai/policy-management/policies

Exports a single policy by its ID. This endpoint is available to any organization user.

```APIDOC
## GET /policies/{policy_id}/export

### Description
Export a single policy by its ID.

### Method
GET

### Endpoint
/policies/{policy_id}/export

### Parameters
#### Path Parameters
- **policy_id** (string) - Required - The unique identifier of the policy.

### Request Example
```
GET /policies/12345/export
```

### Response
#### Success Response (200)
- **id** (string) - The policy ID.
- **name** (string) - The policy name.
- **description** (string) - The policy description.
- **categories** (object) - The policy categories.
- **rule_modes** (object) - Optional per-rule enforcement modes.
- **mode** (string) - The policy mode.
- **threshold** (number) - The policy threshold.
- **scanner_config** (object) - Optional scanner configuration.
- **created_at** (string) - Creation timestamp.
- **updated_at** (string) - Last update timestamp.

#### Response Example
```
{
  "id": "string",
  "name": "string",
  "description": "string",
  "categories": {},
  "rule_modes": {},
  "mode": "string",
  "threshold": 0.0,
  "scanner_config": {},
  "created_at": "string",
  "updated_at": "string"
}
```
```

--------------------------------

### Monitored Message Output

Source: https://docs.grayswan.ai/cygnal/monitor-requests

The resulting text representation of the structured message content parts shown in the previous example.

```text
Hello
Need help planning a trip.
```

--------------------------------

### GET /policies/{policy_id}/versions/{version_id}

Source: https://docs.grayswan.ai/policy-management/policies

Retrieves a policy at a specific version. This endpoint is available to any organization user.

```APIDOC
## GET /policies/{policy_id}/versions/{version_id}

### Description
Get a policy at a specific version.

### Method
GET

### Endpoint
/policies/{policy_id}/versions/{version_id}

### Parameters
#### Path Parameters
- **policy_id** (string) - Required - The unique identifier of the policy.
- **version_id** (string) - Required - The unique identifier of the version.

### Request Example
```
GET /policies/12345/versions/67890
```

### Response
#### Success Response (200)
- **id** (string) - The policy ID.
- **name** (string) - The policy name.
- **description** (string) - The policy description.
- **categories** (object) - The policy categories.
- **rule_modes** (object) - Optional per-rule enforcement modes.
- **mode** (string) - The policy mode.
- **threshold** (number) - The policy threshold.
- **scanner_config** (object) - Optional scanner configuration.
- **created_at** (string) - Creation timestamp.
- **updated_at** (string) - Last update timestamp.

#### Response Example
```
{
  "id": "string",
  "name": "string",
  "description": "string",
  "categories": {},
  "rule_modes": {},
  "mode": "string",
  "threshold": 0.0,
  "scanner_config": {},
  "created_at": "string",
  "updated_at": "string"
}
```
```

--------------------------------

### cURL request to export activity data

Source: https://docs.grayswan.ai/api-reference/activity/export-activity-data

Sends a GET request to the export endpoint. Requires admin role.

```bash
curl -X GET "https://api.grayswan.ai/activity/export"
```
Tokens:
Raw