API Reference - PromptGuard

The proxy endpoints take and return the same bodies as the provider APIs they stand in for: OpenAI’s /chat/completions, /responses and /models, and Anthropic’s /messages. An existing OpenAI or Anthropic integration changes its base URL and adds an X-API-Key header.

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 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:

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

Developer API Authentication

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

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

For detailed authentication setup and code examples, see the Quickstart.

Dashboard API Authentication

/dashboard/* takes a dashboard sign-in, not an API key. These endpoints are the API the dashboard at app.promptguard.co calls. They are not part of the public API, and no API key or long-lived token works on them. Everything under /api/v1 takes your X-API-Key instead (API reference).To script one anyway, sign in with your email and password. This needs an account that has a password, and an email domain that requires SSO is refused. The access token lasts one hour.

# 1. Sign in. The response body carries access_token; the jar keeps the cookies.
curl -c jar.txt https://api.promptguard.co/dashboard/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "..."}'

# 2. Any GET under /dashboard sets the csrf_token cookie.
curl -b jar.txt -c jar.txt https://api.promptguard.co/dashboard/auth/me
CSRF=$(awk '$6 == "csrf_token" { print $7 }' jar.txt)

# 3. Send the cookies on every call, and X-CSRF-Token on POST, PUT, PATCH and DELETE.
curl -b jar.txt -H "X-CSRF-Token: $CSRF" -X POST https://api.promptguard.co/dashboard/...

Where an example shows YOUR_SESSION_TOKEN or YOUR_SESSION_COOKIE, it means the access_token from step 1, sent as Authorization: Bearer <token> or as the access_token cookie. A request acts on your personal organization unless it sends X-Organization-Id.

Base URLs

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

Staging is a separate deployment with its own database, so a key created at app.promptguard.co does not work there.

/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.

Available Endpoints

Chat Completions (OpenAI Compatible)

The primary endpoint for AI requests. It takes and returns OpenAI’s Chat Completions format:

POST /api/v1/chat/completions

Supported parameters:

model - The model id, which also picks the provider. See Integrations for every provider and the model ids each one takes
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 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 for full documentation.

Agent Security

Validate tool calls and monitor agent sessions:

POST /api/v1/agent/validate-tool

See Agent Security reference for full documentation.

Models

List OpenAI’s models, fetched with your OpenAI key: the one in Authorization, else the OpenAI provider key stored for the project or account. With neither, the answer is a 401 missing_api_key, as on /chat/completions; an error from OpenAI comes back with OpenAI’s status (Provider errors).

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

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.

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	20,000 requests	Hard limit (blocks until you upgrade)
Pro	100,000 requests	Hard limit (blocks until you upgrade or enable pay-as-you-go)
Scale	500,000 requests	Metered overage at $0.40/1k to your spend cap (default $500); `429` past the cap
Enterprise	Custom	Soft limit (never blocks)

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.

Limits are enforced per account, so creating additional API keys or organizations does not raise them. The account is the organization owner’s: a teammate’s keys in your organization use your plan’s limit and share your budget. Contact sales@promptguard.co for higher limits.

Response Headers

PromptGuard adds these headers to its responses. Each row says when the header is present:

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`)
`X-PromptGuard-Model-Used`	On a proxied, non-streamed response: the model that produced it. See Fallback Models
`X-PromptGuard-Dashboard-URL`	On a proxied response (allowed, blocked, streamed, or a provider error passed back): the event’s page in the dashboard, `https://app.promptguard.co/dashboard/projects/<project_id>/interactions/<event_id>`. See Event links
`X-PromptGuard-Signature`	On a non-streamed proxied `200` when you sent your PromptGuard key in `X-API-Key`: the hex HMAC-SHA256 of `<timestamp>.<raw response body>`, keyed with that API key
`X-PromptGuard-Signature-Timestamp`	Sent with `X-PromptGuard-Signature`: the Unix time in seconds that the signature covers, the `<timestamp>` above
`X-PromptGuard-RuleOfTwo`	On a proxied request whose `tools` hold all three of Meta’s Agents Rule of Two properties (processes untrustworthy input, accesses sensitive data or systems, changes state or communicates externally): the finding code, `RO2001`. Advisory: the request is never blocked for it. Absent when the toolset holds two or fewer
`X-PromptGuard-RuleOfTwo-Properties`	With `X-PromptGuard-RuleOfTwo`: the properties held, comma-separated and sorted: `sensitive_access`, `state_change_or_external_comms`, `untrustworthy_input`
`X-PromptGuard-RuleOfTwo-Gate`	With `X-PromptGuard-RuleOfTwo`: the smallest set of tool names to remove or put behind human approval to get down to two properties, comma-separated and sorted
`X-PromptGuard-Bot-Warning`	On an `/api/v1/*` request whose traffic pattern looks automated but is let through: `suspicious_behavior`
`X-PromptGuard-Bot-Score`	With `X-PromptGuard-Bot-Warning`, and on a `429` `bot_detected` refusal: the automation risk score, `0` to `1`, to two decimal places
`X-PromptGuard-Threat-IP`	Self-hosted deployments that enable the IP threat list in annotate mode: `1` when the caller’s IP is on a list. The request is allowed
`X-PromptGuard-Threat-IP-Sources`	With `X-PromptGuard-Threat-IP`: the lists that matched, comma-separated (`firehol`, `tor`)

The audit log export (GET /dashboard/audit-log/export, JSON or CSV) stops at a row cap and says so in two headers on every export:

Header	Description
`X-PromptGuard-Export-Truncated`	`true` when the row cap cut the export short, otherwise `false`. A cut-short CSV is also named `audit-log-<date>-partial.csv`
`X-PromptGuard-Export-Row-Limit`	The most rows one export returns

All four verdict headers are listed in Access-Control-Expose-Headers, so browser JavaScript on an allowed origin can read them directly — you do not need a server-side hop to see the decision. The /api/v1/chat/completions response body is never modified: the verdict travels in these headers only, so an OpenAI-compatible client parses the body exactly as it would without PromptGuard in the path.

Error Handling

PromptGuard uses conventional HTTP response codes:

Code	Description	Action
`200`	Success	Request processed normally
`400`	Bad Request	Check the request format
`401`	Unauthorized	Verify API key is valid
`403`	Forbidden	Request blocked by security policy (`request_blocked`), or a plan limit refused it
`422`	Unprocessable Entity	The body failed validation. FastAPI’s `{"detail": [...]}` body, with no `error.code`
`429`	Too Many Requests	Implement exponential backoff
`500`	Server Error	Retry with backoff

Branch on error.code, not the status: several codes share each status, and only some are worth retrying. Every code, with its cause and what to do, is in the error code reference, and an error whose code is listed there carries error.doc_url, a link to its entry.

Error Response Format

A blocked proxy request (from staging, 2026-10-31):

{
  "error": {
    "message": "Request blocked by security policy.",
    "type": "policy_violation",
    "code": "request_blocked",
    "event_id": "4326d70d-b602-4ac2-9315-528a5892b4e1",
    "dashboard_url": "https://app.promptguard.co/dashboard/projects/{project_id}/interactions/4326d70d-b602-4ac2-9315-528a5892b4e1"
  }
}

Blocked requests return 403. The body does not name the threat; the X-PromptGuard-Decision, X-PromptGuard-Threat-Type, X-PromptGuard-Confidence, X-PromptGuard-Event-ID and X-PromptGuard-Dashboard-URL response headers do. dashboard_url links to the event in the dashboard for audit and debugging.

SDKs & Libraries

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

Node.js / TypeScript

Use the official OpenAI SDK with PromptGuard

Python

Use the official OpenAI Python library

Guard API

Standalone content scanning without proxying

Auto-Instrumentation

One line secures all LLM calls

OpenAPI Specification

The complete OpenAPI specification is available for:

Auto-generating client libraries
API testing and validation
Documentation generation

Download OpenAPI Spec

Get the full OpenAPI specification for the Developer API

Next Steps

Quick Start

Get started with PromptGuard in 5 minutes

Python SDK

Make your first secure AI request

API Keys

Learn more about API key management

Guardrails

Configure protection for your use case

​Overview

​Authentication

​Developer API Authentication

​Dashboard API Authentication

​Base URLs

​Available Endpoints

​Chat Completions (OpenAI Compatible)

​Messages (Anthropic Compatible)

​Guard API

​Security Scan

​Security Redact

​Agent Security

​Models

​Usage Statistics

​Policies

​Device Enrollment

​Exceptions

​Tool Requests

​GitHub Webhook

​Rate Limits

​Response Headers

​Error Handling

​Error Response Format

​SDKs & Libraries

Node.js / TypeScript

Python

Guard API

Auto-Instrumentation

​OpenAPI Specification

Download OpenAPI Spec

​Next Steps

Quick Start

Python SDK

API Keys

Guardrails

Overview

Authentication

Developer API Authentication

Dashboard API Authentication

Base URLs

Available Endpoints

Chat Completions (OpenAI Compatible)

Messages (Anthropic Compatible)

Guard API

Security Scan

Security Redact

Agent Security

Models

Usage Statistics

Policies

Device Enrollment

Exceptions

Tool Requests

GitHub Webhook

Rate Limits

Response Headers

Error Handling

Error Response Format

SDKs & Libraries

OpenAPI Specification

Next Steps