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

# API Reference

> PromptGuard REST API reference — authentication, the Guard API, proxy endpoints, agent security, rate limits, and error handling.

<Info>
  The PromptGuard API is fully compatible with OpenAI's API structure, making it a seamless drop-in replacement for your existing integrations.
</Info>

## Overview

PromptGuard provides two types of APIs:

| API Type          | Base URL                               | Authentication        | Purpose                       |
| ----------------- | -------------------------------------- | --------------------- | ----------------------------- |
| **Developer API** | `https://api.promptguard.co/api/v1`    | API Key (`X-API-Key`) | AI requests, usage stats      |
| **Dashboard API** | `https://api.promptguard.co/dashboard` | Session Cookie        | Project management, analytics |

As a customer you will see two path families: `/api/v1/*` is the API-key-authenticated Developer API documented in this reference, while [app.promptguard.co](https://app.promptguard.co) uses its own session-authenticated Dashboard API that is not part of the public API surface.

## Authentication

All PromptGuard API endpoints require authentication. For the Developer API, you'll use two keys:

1. **PromptGuard API key** (in `X-API-Key` header) - Authenticates your PromptGuard account
2. **LLM provider key** (in `Authorization` header) - Your OpenAI/Anthropic key that gets forwarded to the provider

### Developer API Authentication

<CodeGroup>
  ```bash cURL theme={"system"}
  curl https://api.promptguard.co/api/v1/chat/completions \
    -H "X-API-Key: your_api_key" \
    -H "Authorization: Bearer YOUR_OPENAI_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-5-nano",
      "messages": [{"role": "user", "content": "Hello!"}]
    }'
  ```

  ```javascript Node.js theme={"system"}
  import OpenAI from 'openai';

  const openai = new OpenAI({
    // The OpenAI SDK sends apiKey in the Authorization header --
    // PromptGuard forwards this to your upstream provider.
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: 'https://api.promptguard.co/api/v1',
    // Your PromptGuard key authenticates you to PromptGuard.
    defaultHeaders: {
      'X-API-Key': process.env.PROMPTGUARD_API_KEY,
    },
  });

  const completion = await openai.chat.completions.create({
    model: "gpt-5-nano",
    messages: [{ role: 'user', content: 'Hello!' }]
  });
  ```
</CodeGroup>

<Note>
  For detailed authentication setup and code examples, see the [Quickstart](/quickstart).
</Note>

### Dashboard API Authentication

For dashboard applications, use session-based authentication:

```bash theme={"system"}
curl https://api.promptguard.co/dashboard/projects \
  -H "Cookie: session=YOUR_SESSION_COOKIE"
```

## Base URLs

| Environment    | URL                                         |
| -------------- | ------------------------------------------- |
| **Production** | `https://api.promptguard.co/api/v1`         |
| **Staging**    | `https://staging-api.promptguard.co/api/v1` |

<Note>
  **`/api/v1/proxy/...` also works.** Every endpoint below is mounted a second time
  under a `/proxy` prefix — `/api/v1/guard` and `/api/v1/proxy/guard` are the same
  endpoint with the same behaviour. If you already call the `/proxy` form, it keeps
  working and there is nothing to migrate.

  This reference documents the shorter `/api/v1/...` form only. Publishing both
  produced two pages per endpoint, which left search engines and coding assistants
  guessing at which URL was canonical. Prefer `/api/v1/...` in new code.
</Note>

## Available Endpoints

### Chat Completions (OpenAI Compatible)

The primary endpoint for AI requests. Fully compatible with OpenAI's API:

```
POST /api/v1/chat/completions
```

**Supported parameters:**

* `model` - Any supported LLM model (OpenAI, Anthropic, Google, Mistral, DeepSeek, Cohere, Groq, Azure OpenAI). See [Supported LLM Providers](/guides/llm-providers) for complete model list
* `messages` - Array of message objects
* `temperature`, `max_tokens`, `top_p`, etc.
* `stream` - Enable streaming responses
* `user` - Unique user identifier for tracking

### Messages (Anthropic Compatible)

Anthropic-style messages endpoint for native Anthropic SDK integrations (`messages.create()`). Routes through the same policy engine as `/chat/completions`:

```
POST /api/v1/messages
```

### Guard API

Scan content for threats without proxying to an LLM provider. Accepts structured messages with direction and context:

```
POST /api/v1/guard
```

See [Guard API reference](/api-reference/guard) for full documentation.

### Security Scan

Analyze raw text for prompt injection, jailbreaks, and other threats:

```
POST /api/v1/security/scan
```

### Security Redact

Strip PII from text and return both original and redacted versions:

```
POST /api/v1/security/redact
```

See [Security Scan & Redact reference](/api-reference/security-endpoints) for full documentation.

### Agent Security

Validate tool calls and monitor agent sessions:

```
POST /api/v1/agent/validate-tool
```

See [Agent Security reference](/api-reference/agent-security) for full documentation.

### Models

List available models:

```
GET /api/v1/models
```

### Usage Statistics

Get your current usage:

```
GET /api/v1/usage/stats
```

### Policies

List the active policies enforced for your API key's project (project policies plus account-level global policies, highest priority first). Policies are created and edited in the dashboard — this endpoint is read-only:

```
GET /api/v1/policies
```

### Device Enrollment

Enroll a device (used by the desktop agent and CLI):

```
POST /api/v1/enroll
```

### Exceptions

Create and manage temporary policy exceptions:

```
POST /api/v1/exceptions
GET  /api/v1/exceptions
GET  /api/v1/exceptions/active
GET  /api/v1/exceptions/{exception_id}
POST /api/v1/exceptions/{exception_id}/cancel
```

### Tool Requests

Request and track approval for blocked tools:

```
GET  /api/v1/tool-requests
POST /api/v1/tool-requests
POST /api/v1/tool-requests/{request_id}/cancel
```

### GitHub Webhook

Receiver for PromptGuard GitHub App webhook events (called by GitHub, not by your code):

```
POST /api/v1/github/webhook
```

<Note>
  Core endpoints are also mounted under a `/api/v1/proxy/*` alias (e.g. `POST /api/v1/proxy/chat/completions`) for backwards compatibility. New integrations should use the `/api/v1/*` paths.
</Note>

## Rate Limits

PromptGuard applies two independent limits, both scoped **per account** (not per API key):

**Per-minute rate limit** (requests per minute):

| Plan           | Rate Limit                    |
| -------------- | ----------------------------- |
| **Free**       | 60 rpm                        |
| **Pro**        | 300 rpm                       |
| **Scale**      | 600 rpm                       |
| **Enterprise** | 1,000 rpm (custom on request) |

**Monthly request quota** (per account):

| Plan           | Monthly Limit      | Type                                   |
| -------------- | ------------------ | -------------------------------------- |
| **Free**       | 10,000 requests    | Hard limit (blocks when exceeded)      |
| **Pro**        | 100,000 requests   | Hard limit (blocks when exceeded)      |
| **Scale**      | 1,000,000 requests | Soft limit (alerts only, never blocks) |
| **Enterprise** | Custom             | Soft limit (never blocks)              |

<Note>
  **Infrastructure anti-abuse limit**: A separate Cloud Armor layer enforces a per-IP request limit at the edge. This is independent of your plan's per-account rate limit and monthly quota.
</Note>

<Note>
  Limits are enforced per account, so creating additional API keys does not raise them. Contact [sales@promptguard.co](mailto:sales@promptguard.co) for higher limits.
</Note>

## Response Headers

PromptGuard adds helpful headers to every response:

| Header                      | Description                                                            |
| --------------------------- | ---------------------------------------------------------------------- |
| `X-PromptGuard-Event-ID`    | Unique identifier for tracking this request                            |
| `X-PromptGuard-Decision`    | Security decision: `allow`, `block`, or `redact`                       |
| `X-PromptGuard-Confidence`  | Confidence score of the security decision (0.0 - 1.0)                  |
| `X-PromptGuard-Threat-Type` | Type of threat detected (e.g., `prompt_injection`, `pii_leak`, `none`) |

## Error Handling

PromptGuard uses conventional HTTP response codes:

| Code  | Description       | Action                                                                              |
| ----- | ----------------- | ----------------------------------------------------------------------------------- |
| `200` | Success           | Request processed normally                                                          |
| `400` | Bad Request       | Check request format or security policy violation                                   |
| `401` | Unauthorized      | Verify API key is valid                                                             |
| `403` | Forbidden         | Request blocked by security policy, or check subscription status / API key validity |
| `429` | Too Many Requests | Implement exponential backoff                                                       |
| `500` | Server Error      | Retry with backoff                                                                  |

### Error Response Format

```json theme={"system"}
{
  "error": {
    "message": "Request blocked by security policy",
    "type": "policy_violation",
    "code": "request_blocked",
    "event_id": "evt_abc123xyz",
    "dashboard_url": "https://app.promptguard.co/dashboard/projects/{project_id}/interactions?event_id=evt_abc123xyz"
  }
}
```

Blocked requests return **403**. The optional `dashboard_url` links directly to the event in the dashboard for audit and debugging.

### Security Policy Violations

When a request is blocked for security reasons:

```json theme={"system"}
{
  "error": {
    "message": "Prompt injection detected",
    "type": "policy_violation",
    "code": "prompt_injection_detected",
    "event_id": "evt_abc123xyz",
    "details": {
      "threat_type": "instruction_override",
      "confidence": 0.95
    }
  }
}
```

## SDKs & Libraries

PromptGuard works with existing OpenAI/Anthropic SDKs by simply changing the base URL:

<CardGroup cols={2}>
  <Card title="Node.js / TypeScript" icon="node-js" href="/guides/node-sdk">
    Use the official OpenAI SDK with PromptGuard
  </Card>

  <Card title="Python" icon="python" href="/guides/python-sdk">
    Use the official OpenAI Python library
  </Card>

  <Card title="Guard API" icon="shield-check" href="/api-reference/guard">
    Standalone content scanning without proxying
  </Card>

  <Card title="Auto-Instrumentation" icon="wand-magic-sparkles" href="/guides/python-sdk">
    One line secures all LLM calls
  </Card>
</CardGroup>

## OpenAPI Specification

The complete OpenAPI specification is available for:

* Auto-generating client libraries
* API testing and validation
* Documentation generation

<Card title="Download OpenAPI Spec" icon="file-code" href="/api-reference/openapi-developer.json">
  Get the full OpenAPI specification for the Developer API
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get started with PromptGuard in 5 minutes
  </Card>

  <Card title="Python SDK" icon="python" href="/guides/python-sdk">
    Make your first secure AI request
  </Card>

  <Card title="API Keys" icon="key" href="/api-reference/api-keys">
    Learn more about API key management
  </Card>

  <Card title="Security Rules" icon="shield" href="/security/overview">
    Configure protection for your use case
  </Card>
</CardGroup>