SafePrompt

https://docs.safeprompt.dev
Admin
SafePrompt is a prompt injection detection API that validates user input before it reaches language...
Tokens:7,144
Snippets:91
Trust Score:5.2
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install SafePrompt SDK

Source: https://docs.safeprompt.dev/quick-start

Install the official npm package for a typed client. This is an optional step as you can also call the HTTP API directly.

```bash
npm install safeprompt
```

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

### Install safeprompt-middleware

Source: https://docs.safeprompt.dev/installation

Install the official SafePrompt middleware package using npm. This package is required for Express and Next.js integrations.

```bash
npm install safeprompt-middleware
```

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

### Implement Fail-Open Strategy for SafePrompt

Source: https://docs.safeprompt.dev/quick-start

This example demonstrates a fail-open strategy. If the SafePrompt API is unreachable or times out, the request proceeds to avoid blocking legitimate users.

```javascript
try {
  const result = await validatePrompt(userInput);
  if (!result.safe) {
    return { error: 'Invalid request' };
  }
} catch (error) {
  // Fail open: Allow request if validation service is down
  console.error('SafePrompt validation failed:', error);
}
```

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

### SafePrompt API Response Example

Source: https://docs.safeprompt.dev/quick-start

This is an example of the JSON response from the SafePrompt API. It includes a safety verdict, confidence score, detected threats, and processing time.

```json
{
  "safe": false,
  "confidence": 0.95,
  "threats": ["prompt_injection"],
  "processingTime": 245,
  "sessionId": "sess_abc123"
}
```

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

### Implement Caching for Prompt Validation

Source: https://docs.safeprompt.dev/quick-start

This example shows how to implement caching for prompt validation results to improve performance in high-traffic applications. It includes a simple hash function and cache management.

```javascript
const cache = new Map();
const CACHE_TTL = 60000; // 1 minute
const MAX_CACHE_SIZE = 1000;

// Simple hash function for caching (use crypto.createHash in production)
function hashPrompt(prompt) {
  return prompt.toLowerCase().trim();
}

async function validateWithCache(prompt) {
  const hash = hashPrompt(prompt);
  const cached = cache.get(hash);

  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.result;
  }

  const result = await validatePrompt(prompt);

  // Prevent cache from growing unbounded
  if (cache.size >= MAX_CACHE_SIZE) {
    const firstKey = cache.keys().next().value;
    cache.delete(firstKey);
  }

  cache.set(hash, { result, timestamp: Date.now() });
  return result;
}
```

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

### Protect Conversational AI with Multi-Turn Protection

Source: https://docs.safeprompt.dev/quick-start

This example demonstrates how to track session tokens to detect multi-turn attacks in conversational AI. The session token is included in the request and updated with the response.

```javascript
let sessionToken = null;

async function validateConversationTurn(userInput, clientIP) {
  const requestBody = {
    prompt: userInput
  };

  // Include session_token for multi-turn tracking (if we have one)
  if (sessionToken) {
    requestBody.session_token = sessionToken;
  }

  const result = await fetch('https://api.safeprompt.dev/api/v1/validate', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'X-User-IP': clientIP,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(requestBody)
  });

  const data = await result.json();
  sessionToken = data.session_token;  // Store for next turn
  return data;
}
```

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

### SafePrompt Structured Result Example

Source: https://docs.safeprompt.dev/how-it-works

An example of the structured JSON output returned by SafePrompt after processing a request. This includes safety verdict, confidence score, detected threats, and processing metadata.

```json
{
  "safe": false,
  "confidence": 0.98,
  "threats": ["prompt_injection", "instruction_override"],
  "processingTimeMs": 4,
  "passesUsed": 1,
  "request_id": "uuid-for-audit-trail",
  "timestamp": "2026-03-19T10:00:00.000Z"
}
```

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

### Get End User IP Address

Source: https://docs.safeprompt.dev/api-reference

Extracts the end user's IP address for the X-User-IP header. Use the appropriate snippet for your framework.

```javascript
// Express.js
const clientIp = req.headers['x-forwarded-for'] || req.connection.remoteAddress;
```

```javascript
// Next.js
const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
```

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

### Initialize SafePrompt SDK and Validate Prompt

Source: https://docs.safeprompt.dev/quick-start

Use the SDK to initialize SafePrompt with your API key and validate user input. The result indicates if the prompt is safe and lists any detected threats.

```javascript
import SafePrompt from 'safeprompt';

const sp = new SafePrompt({ apiKey: 'YOUR_API_KEY' });

const result = await sp.check(userInput, { userIP: clientIP });
if (!result.safe) {
  throw new Error(`Blocked: ${result.threats?.[0] || 'Security threat detected'}`);
}
```

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

### Using a Different Provider

Source: https://docs.safeprompt.dev/installation

Configure the `createGuard` function to use a custom ai-security-gateway-spec compliant provider instead of the default SafePrompt API.

```typescript
createGuard({
  provider: 'https://your-provider.com',
  apiKey: process.env.YOUR_PROVIDER_KEY,
})
```

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

### Express Full Configuration

Source: https://docs.safeprompt.dev/installation

Configure `createGuard` with advanced options for Express applications, including mode, field name, fail-open behavior, and custom block/error handlers.

```typescript
app.use('/api/chat', createGuard({
  apiKey: process.env.GUARD_API_KEY,
  mode: 'balanced',       // 'fast' | 'balanced' | 'strict'
  fieldName: 'message',   // which req.body field to validate (default: 'prompt')
  failOpen: true,         // allow through if SafePrompt is unreachable (default: false)
  onBlock: (req, res, result) => {
    res.status(400).json({ error: 'Unsafe prompt', threats: result.threats });
  },
  onError: (req, res, err) => {
    console.error('SafePrompt error:', err);
    res.status(500).json({ error: 'Validation failed' });
  },
}));
```

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

### SafePrompt Performance Metrics

Source: https://docs.safeprompt.dev/how-it-works

Details the latency, cost, and applicability of each stage in the SafePrompt detection pipeline.

```text
Stage| Latency| Cost| Applies to  
---|---|---|---
Pattern Detection| <5ms| $0| All requests  
External Ref Detection| <5ms| $0| Uncertain after Stage 1  
AI Pass 1| ~50ms| Minimal| Uncertain after Stage 2  
AI Pass 2| ~100ms| Higher| Low-confidence Pass 1 only  
```

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

### Validate Prompt with Python

Source: https://docs.safeprompt.dev/api-reference

Use this Python snippet to send a user prompt to the Safeprompt API for validation. Ensure the SAFEPROMPT_API_KEY environment variable is set.

```python
import requests
import os

def check_prompt(user_input, client_ip):
    response = requests.post(
        'https://api.safeprompt.dev/api/v1/validate',
        headers={
            'X-API-Key': os.environ["SAFEPROMPT_API_KEY"],
            'X-User-IP': client_ip,
            'Content-Type': 'application/json'
        },
        json={'prompt': user_input}
    )

    result = response.json()

    if not result['safe']:
        threats = result.get('threats', ['Unknown threat'])
        raise ValueError(f"Blocked: {', '.join(threats)}")

    return result
```

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

### HTTP API Validation (cURL)

Source: https://docs.safeprompt.dev/installation

Validate a prompt using the SafePrompt HTTP API directly from the command line with cURL. Requires API key and client IP.

```bash
curl -X POST https://api.safeprompt.dev/api/v1/validate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-User-IP: CLIENT_IP" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello, how can you help me?"}'
```

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

### Validate Prompt using cURL

Source: https://docs.safeprompt.dev/api-reference

Demonstrates how to validate a single prompt using a cURL command. Ensure you replace YOUR_API_KEY with your actual key.

```bash
curl -X POST https://api.safeprompt.dev/api/v1/validate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-User-IP: 203.0.113.45" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello world"}'
```

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

### SafePrompt Detection Pipeline Flow

Source: https://docs.safeprompt.dev/how-it-works

Illustrates the sequential flow of a user request through SafePrompt's four detection stages. Each stage can exit early if a decision is reached.

```text
User input
↓
Stage 1: Pattern Detection<5ms · $0
↓ (if uncertain)
Stage 2: External Reference Detection<5ms · $0
↓ (if uncertain)
Stage 3: AI Validation — Pass 1~50ms · fast model
↓ (if still uncertain)
Stage 4: AI Validation — Pass 2~100ms · deep analysis
↓
Result: safe / unsafe + threats + confidence
```

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

### Validate Prompt using JavaScript SDK

Source: https://docs.safeprompt.dev/api-reference

Uses the recommended SafePrompt SDK to check a prompt for injection attacks. The user IP is passed in the options.

```javascript
// Using SDK (recommended)
import SafePrompt from 'safeprompt';

const client = new SafePrompt({ apiKey: process.env.SAFEPROMPT_API_KEY });

const result = await client.check('Ignore previous instructions...', {
  userIP: req.headers['x-forwarded-for'] || req.connection.remoteAddress
});

if (!result.safe) {
  throw new Error(`Blocked: ${result.threats.join(', ')}`);
}
```

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

### Validate Prompt with PHP

Source: https://docs.safeprompt.dev/api-reference

This PHP snippet demonstrates how to validate user input using the Safeprompt API via cURL. It requires the SAFEPROMPT_API_KEY to be set in environment variables.

```php
$clientIp = $_SERVER['HTTP_X_FORWARDED_FOR'] ?? $_SERVER['REMOTE_ADDR'];

$ch = curl_init('https://api.safeprompt.dev/api/v1/validate');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $_ENV['SAFEPROMPT_API_KEY'],
    'X-User-IP: ' . $clientIp,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'prompt' => $userInput
]));

$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);

if (!$result['safe']) {
    die('Threat detected: ' . implode(', ', $result['threats']));
}
```

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

### Test SafePrompt API with Placeholder IP

Source: https://docs.safeprompt.dev/quick-start

When the end user's IP is unavailable, use a placeholder IP from the RFC 5737 TEST-NET-3 range for testing and development purposes.

```bash
# Use TEST-NET-3 addresses (203.0.113.0/24) for testing
curl -X POST https://api.safeprompt.dev/api/v1/validate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-User-IP: 203.0.113.45" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello world"}'
```

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

### Next.js App Router Integration

Source: https://docs.safeprompt.dev/installation

Wrap your Next.js App Router route handler with `withGuardRoute` to protect it. The validated prompt is available via the original request.

```typescript
// app/api/chat/route.ts
import { withGuardRoute } from 'safeprompt-middleware/next';

async function POST(req: Request) {
  const { message } = await req.json();
  // message has passed injection check
  return Response.json({ reply: 'response from LLM' });
}

export { withGuardRoute(POST, {
  apiKey: process.env.GUARD_API_KEY!,
  fieldName: 'message',
}) as POST };
```

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

### Validate Prompt using HTTP API

Source: https://docs.safeprompt.dev/api-reference

Directly calls the SafePrompt /api/v1/validate endpoint using the fetch API. Requires manual construction of headers and body.

```javascript
// Using HTTP API directly
async function checkPrompt(userInput, clientIp) {
  const response = await fetch('https://api.safeprompt.dev/api/v1/validate', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.SAFEPROMPT_API_KEY,
      'X-User-IP': clientIp,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ prompt: userInput })
  });

  return await response.json();
}
```

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

### Next.js Pages Router Integration

Source: https://docs.safeprompt.dev/installation

Integrate SafePrompt into a Next.js Pages Router API route using the `withGuard` higher-order function. The prompt in `req.body` is guaranteed to be safe.

```typescript
// pages/api/chat.ts
import { withGuard } from 'safeprompt-middleware/next';
import type { NextApiRequest, NextApiResponse } from 'next';

async function handler(req: NextApiRequest, res: NextApiResponse) {
  // req.body.prompt is safe
  res.json({ reply: 'response from LLM' });
}

export default withGuard(handler, {
  apiKey: process.env.GUARD_API_KEY!,
  fieldName: 'message',
});
```

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

### Express Basic Integration

Source: https://docs.safeprompt.dev/installation

Integrate `createGuard` as route-level middleware in an Express application to protect a specific route. It validates the prompt before your handler.

```typescript
import express from 'express';
import { createGuard } from 'safeprompt-middleware';

const app = express();
app.use(express.json());

// Protect a single route
app.use('/api/chat', createGuard({
  apiKey: process.env.GUARD_API_KEY,
}));

app.post('/api/chat', (req, res) => {
  // req.body.prompt is safe — pass to your LLM here
  res.json({ reply: 'response from LLM' });
});
```

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

### Validate Prompt

Source: https://docs.safeprompt.dev/api-reference

This endpoint validates a given user prompt for safety. It requires an API key and the user's IP address for security and rate limiting.

```APIDOC
## POST /api/v1/validate

### Description
Validates a user prompt for safety. Returns a JSON object indicating if the prompt is safe and details about any detected threats.

### Method
POST

### Endpoint
/api/v1/validate

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your SafePrompt API key.
- **X-User-IP** (string) - Required - The IP address of the end-user making the request.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **prompt** (string) - Required - The user input to validate.

### Request Example
```json
{
  "prompt": "This is a test prompt."
}
```

### Response
#### Success Response (200)
- **safe** (boolean) - True if the prompt is safe, false otherwise.
- **threats** (array of strings) - Optional - A list of detected threats if `safe` is false.

#### Response Example
```json
{
  "safe": true
}
```

#### Error Responses
- **400** - Bad request (invalid input or missing X-User-IP)
- **401** - Unauthorized (invalid API key)
- **403** - Forbidden (subscription expired)
- **429** - Too many requests (rate limited)
- **500** - Internal server error
```

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

### HTTP API Validation (Python)

Source: https://docs.safeprompt.dev/installation

Validate user input using the SafePrompt HTTP API with Python's requests library. Handles blocking unsafe prompts and raises an error.

```python
import requests

result = requests.post(
    'https://api.safeprompt.dev/api/v1/validate',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'X-User-IP': client_ip,
        'Content-Type': 'application/json',
    },
    json={'prompt': user_input}
).json()

if not result['safe']:
    raise ValueError(f"Blocked: {result['threats'][0]}")
```

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

### Validate User Prompts via HTTP API

Source: https://docs.safeprompt.dev/quick-start

Call the SafePrompt HTTP API directly to validate user input. Ensure you include your API key and the end user's IP address in the headers.

```javascript
const response = await fetch('https://api.safeprompt.dev/api/v1/validate', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'X-User-IP': clientIpAddress, // End user's IP address
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ prompt: userInput })
});

const result = await response.json();
if (!result.safe) {
  throw new Error(`Blocked: ${result.threats?.[0] || 'Security threat detected'}`);
}
```

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

### POST /api/v1/validate

Source: https://docs.safeprompt.dev/api-reference

Validates a single prompt for injection attacks. It requires authentication headers and accepts a JSON payload with the prompt and optional parameters for mode, sensitivity, and statistics inclusion.

```APIDOC
## POST /api/v1/validate

### Description
Validate a single prompt for injection attacks.

### Method
POST

### Endpoint
https://api.safeprompt.dev/api/v1/validate

### Parameters
#### Request Body
- **prompt** (string) - Required - The prompt to validate
- **mode** (string) - Optional - Validation mode: `optimized` (default), `standard`, `ai-only`, `with-cache`
- **sensitivity** (string) - Optional - Detection sensitivity: `lenient`, `balanced` (default), `strict`
- **include_stats** (boolean) - Optional - Include performance statistics

### Request Example
```json
{
  "prompt": "Hello world"
}
```

### Response
#### Success Response (200)
- **safe** (boolean) - Is the prompt safe to use?
- **confidence** (float) - 0-1: How confident is the verdict?
- **threats** (array) - Detected threat types (empty if safe)
- **processingTime** (integer) - Response time in milliseconds
- **detectionMethod** (string) - Detection stage used (`pattern_detection`, `external_reference_detection`, `ai_validation`)
- **reasoning** (string) - Why this verdict?

#### Response Example (Threat Detected)
```json
{
  "safe": false,
  "confidence": 0.98,
  "threats": ["prompt_injection", "external_reference"],
  "processingTime": 15,
  "detectionMethod": "pattern_detection",
  "reasoning": "Detected attempt to override system instructions and fetch external URL"
}
```
```

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

### Express Request Attachment

Source: https://docs.safeprompt.dev/installation

Details the structure of the `req.guardResult` object attached to the request after a safe prompt is processed by the Express middleware.

```json
{
  "safe": true,
  "threats": [],
  "confidence": 0.99,
  "processingTimeMs": 4,
  "passesUsed": 1,
  "request_id": "uuid",
  "timestamp": "2026-03-19T..."
}
```
Tokens:
Raw