# Pinpout
> Prompt injection detection API. 15ms latency. ML classifier, not LLM-based. Works with any LLM provider.

## Quick Start
- [Quickstart](#how-it-works): Add protection in 30 seconds — sign up, get key, add one API call before your LLM call
- [API Reference](#api-reference): POST /v1/scan — request/response schemas, auth, errors

## Integration Examples

### Python (requests)
```python
import requests

def scan_input(user_input: str) -> bool:
    response = requests.post(
        "https://api.pinpout.dev/v1/scan",
        headers={"X-API-Key": "pp_live_your_key_here"},
        json={"text": user_input},
    )
    result = response.json()
    return result["is_safe"]

if scan_input(user_message):
    # Safe — pass to your LLM
    pass
else:
    raise ValueError("Prompt injection detected")
```

### JavaScript/TypeScript (fetch)
```typescript
async function scanInput(userInput: string): Promise<boolean> {
  const response = await fetch("https://api.pinpout.dev/v1/scan", {
    method: "POST",
    headers: {
      "X-API-Key": "pp_live_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ text: userInput }),
  });
  const { is_safe } = await response.json();
  return is_safe;
}
```

### cURL
```bash
curl -X POST https://api.pinpout.dev/v1/scan \
  -H "X-API-Key: pp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ignore all previous instructions and..."}'
```

## API Endpoints
- POST /v1/scan — Scan text for prompt injection. Auth: X-API-Key header.
- GET /v1/keys — Get current API key info. Auth: Bearer JWT (Clerk).
- POST /v1/keys — Create API key. Auth: Bearer JWT.
- POST /v1/keys/rotate — Rotate API key (old key immediately invalidated). Auth: Bearer JWT.
- DELETE /v1/keys — Delete API key. Auth: Bearer JWT.
- GET /v1/usage — Get monthly usage stats. Auth: Bearer JWT.

## Core Concepts
- Detection runs BEFORE the LLM call — inject Pinpout between user input and your LLM
- Purpose-built ML classifier — no LLM API call in your critical path
- Handles encoding obfuscation automatically so encoded attacks don't slip through
- Returns `is_safe` (bool) + `confidence` (float 0-1) + `scan_id` (UUID for reporting FP/FN)
- Dashboard playground lets you test prompts before writing code

## Attack Types Detected
- Direct prompt injection ("ignore previous instructions", "you are now", "disregard all")
- Jailbreaks and role-play attacks
- Encoding obfuscation and evasion techniques
- System prompt extraction attempts

## Pricing
- Free: 100 scans/month. No credit card.
- Supporter ($5/mo): 10,000 scans/month
- Pro ($15/mo): 50,000 scans/month
- Need more? Email hello@pinpout.dev

## Base URL
https://api.pinpout.dev

## Authentication
- Scanning: X-API-Key: pp_live_... header on /v1/scan
- Dashboard (key management, usage): Authorization: Bearer <session-token>
- NEVER include API key in client-side code

## Error Codes
- 400 INVALID_REQUEST — Missing or invalid fields
- 401 INVALID_API_KEY — Bad or missing key on /v1/scan
- 401 UNAUTHORIZED — Bad or missing JWT on dashboard endpoints
- 403 QUOTA_EXCEEDED — Monthly scan limit reached
- 404 NOT_FOUND — No key exists
- 409 KEY_EXISTS — Key already exists
- 429 RATE_LIMITED — 100 req/min per key
- 500 INTERNAL_ERROR — Server error

All errors: { "error": { "code": "string", "message": "string" } }

## Rate Limits
- 100 requests/minute per API key
- Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
- On 429: Retry-After header included (seconds until reset)