API Reference

Base URL

https://api.safeprompt.dev

Authentication

All API requests require two headers:

How to get the end user's IP:

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

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

Endpoint

POST /api/v1/validate

Validate a single prompt for injection attacks.

Request

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"}'

Request Body

{
  "prompt": "string",           // Required: The prompt to validate
  "mode": "optimized",          // Optional: standard, optimized, ai-only, with-cache
  "include_stats": false        // Optional: Include performance statistics
}

Response

{
  "safe": true,                // Boolean: Is the prompt safe to use?
  "confidence": 0.95,          // Float 0-1: How confident is the verdict?
  "threats": [],               // Array: Detected threat types (empty if safe)
  "processingTime": 250,       // Integer: Response time in milliseconds
  "detectionMethod": "pattern_detection",  // String: Detection stage used
  "reasoning": "No security threats detected"  // String: Why this verdict?
}

Example Response (Threat Detected)

{
  "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"
}

Code Examples

JavaScript/Node.js

// 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(', ')}`);
}

// 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();
}

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

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']));
}

Error Codes

Rate Limits

Next Steps