Appearance
OpenAI-Compatible API
GhostAI provides an OpenAI-compatible API that can be used as a drop-in replacement for OpenAI in third-party tools and AI coding assistants.
Overview
This API enables you to use GhostAI's PII and secrets protection with any tool that supports the OpenAI API format:
AI Coding Tools (Vibe Coding)
- Continue - VS Code AI assistant (chat, autocomplete, planning)
- Cursor - AI-first code editor
- Cline - VS Code AI coding agent
- Aider - Terminal-based AI pair programmer
- Windsurf - AI-powered IDE
- Google Antigravity - Agent-first IDE
Frameworks & Platforms
- OpenWebUI - Self-hosted ChatGPT-style interface
- n8n - Workflow automation
- LangChain - LLM application framework
- OpenClaw - Multi-agent orchestration
- Any OpenAI SDK client - Python, JavaScript, Go, etc.
All generation requests (chat, completions, responses) pass through GhostAI's PII and secrets protection layer before reaching the LLM. The one exception is /v1/embeddings, which is a pass-through endpoint by design -- see its section for details.
Anthropic/Claude Support
For tools using Claude models (Claude Code, Cline with Anthropic, Continue with Anthropic), see the Anthropic-compatible endpoint at POST /v1/messages.
Base URL
https://your-ghostai-instance.com/v1Authentication
Generate an API key from Settings → API Keys in the GhostAI dashboard. For copy-paste snippets and a connection test, use Settings → Keys → Connect a tool (see the AI tool setup guide).
API keys start with gst_ prefix and can be used via:
bash
# Authorization header (recommended)
Authorization: Bearer gst_your_api_key_here
# X-API-Key header (alternative)
X-API-Key: gst_your_api_key_hereEndpoints
POST /v1/chat/completions
Create a chat completion with automatic PII protection.
Request:
bash
curl https://your-ghostai-instance.com/v1/chat/completions \
-H "Authorization: Bearer gst_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o-mini",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "My SSN is 123-45-6789. Help me with taxes."}
],
"temperature": 0.7,
"max_tokens": 1000,
"stream": false
}'Response:
json
{
"id": "chatcmpl-ghost-abc123def456",
"object": "chat.completion",
"created": 1706745600,
"model": "openai/gpt-4o-mini",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "I'd be happy to help with your taxes..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 50,
"completion_tokens": 100,
"total_tokens": 150
},
"ghost_pii_detected": 1,
"ghost_session_id": "sess_xyz789"
}Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Model ID (e.g., gpt-4o-mini, openai/gpt-4o-mini) |
messages | array | Yes | Array of message objects |
temperature | number | No | Sampling temperature (0-2, default: 1.0) |
top_p | number | No | Nucleus sampling (0-1, default: 1.0) |
max_tokens | integer | No | Maximum tokens in response |
stream | boolean | No | Enable streaming (default: false) |
stop | string/array | No | Stop sequences |
presence_penalty | number | No | Presence penalty (-2 to 2) |
frequency_penalty | number | No | Frequency penalty (-2 to 2) |
GhostAI-Specific Parameters
| Parameter | Type | Description |
|---|---|---|
ghost_session_id | string | Session ID for PII token tracking (optional) |
ghost_detokenize | boolean | Set to false to keep tokens in response (default: true) |
GET /v1/models
List available models from the configured LLM provider.
Request:
bash
curl https://your-ghostai-instance.com/v1/models \
-H "Authorization: Bearer gst_your_api_key_here"Response:
json
{
"object": "list",
"data": [
{
"id": "openai/gpt-4o-mini",
"object": "model",
"created": 1706745600,
"owned_by": "ghostai-openrouter"
},
{
"id": "openai/gpt-4o",
"object": "model",
"created": 1706745600,
"owned_by": "ghostai-openrouter"
}
]
}GET /v1/models/
Get information about a specific model.
bash
curl https://your-ghostai-instance.com/v1/models/gpt-4o-mini \
-H "Authorization: Bearer gst_your_api_key_here"POST /v1/completions
Legacy Completions API for fill-in-the-middle (FIM) and autocomplete. Used by coding tools like Continue for inline code suggestions.
Request:
bash
curl https://your-ghostai-instance.com/v1/completions \
-H "Authorization: Bearer gst_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o-mini",
"prompt": "def calculate_average(numbers):\n ",
"max_tokens": 200,
"temperature": 0.2,
"stream": false
}'Response:
json
{
"id": "cmpl-ghost-abc123def456",
"object": "text_completion",
"created": 1706745600,
"model": "openai/gpt-4o-mini",
"choices": [
{
"index": 0,
"text": "if not numbers:\n return 0\n return sum(numbers) / len(numbers)",
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 25,
"total_tokens": 37
}
}Completions Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Model ID (e.g., gpt-4o-mini, openai/gpt-4o-mini) |
prompt | string or array | Yes | Text to complete |
max_tokens | integer | No | Maximum tokens to generate (default: 512) |
temperature | number | No | Sampling temperature (0-2, default: 1.0) |
stop | string/array | No | Stop sequences |
suffix | string | No | Suffix for fill-in-the-middle (FIM) completion |
stream | boolean | No | Enable streaming (default: false) |
Streaming responses use object: "text_completion" chunks with choices[].text deltas, distinct from the chat.completion.chunk format used by /v1/chat/completions.
POST /v1/responses
OpenAI Responses API, used by newer OpenAI SDKs and tools like Continue when configured with GPT-5 or o-series models.
Request:
bash
curl https://your-ghostai-instance.com/v1/responses \
-H "Authorization: Bearer gst_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"input": "My SSN is 123-45-6789. Help me file taxes.",
"max_output_tokens": 1000,
"stream": false
}'The input field accepts a plain string or an array of message objects:
json
{
"model": "openai/gpt-4o",
"input": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "My email is john@example.com. Draft a reply."}
],
"instructions": "Be concise.",
"temperature": 0.7
}Response:
json
{
"id": "resp_ghost_abc123def456",
"object": "response",
"created_at": 1706745600,
"model": "openai/gpt-4o",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "I'd be happy to help you file your taxes..."
}
]
}
],
"usage": {
"input_tokens": 30,
"output_tokens": 85,
"total_tokens": 115
}
}Responses Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Model ID |
input | string or array | Yes | Prompt text or array of message objects |
instructions | string | No | System-level instructions |
max_output_tokens | integer | No | Maximum tokens in response |
temperature | number | No | Sampling temperature (0-2) |
stream | boolean | No | Enable streaming (default: false) |
Streaming uses Responses API-specific SSE events: response.created, response.output_item.added, response.output_text.delta, response.output_text.done, and response.completed.
POST /v1/embeddings
Create vector embeddings for text, compatible with the OpenAI Embeddings API. Used by IDE integrations (Continue, Cursor, Cline) for codebase indexing and by RAG pipelines.
Pass-through endpoint -- no PII protection
Unlike every other endpoint on this page, /v1/embeddings forwards your input to the model provider verbatim, with no PII detection, tokenization, or secrets scanning. Replacing PII with tokens would change the meaning of the text and silently corrupt the resulting vectors (and any similarity search built on them), so protection is deliberately skipped.
Only send content you are comfortable sharing with the upstream provider. Every request is audit-logged (metadata only -- never the content itself) with an explicit pass-through marker. Administrators can disable this endpoint via the embeddings_api feature flag or block embedding models through the model allowlist.
Request:
bash
curl https://your-ghostai-instance.com/v1/embeddings \
-H "Authorization: Bearer gst_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-3-small",
"input": "The quick brown fox jumps over the lazy dog"
}'input also accepts an array (up to 2048 items) for batch embedding:
json
{
"model": "text-embedding-3-small",
"input": ["first chunk", "second chunk", "third chunk"]
}Response:
json
{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [-0.02084, -0.01689, -0.00451, "..."]
}
],
"model": "text-embedding-3-small",
"usage": {
"prompt_tokens": 9,
"total_tokens": 9
}
}Embeddings Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Embedding model ID (e.g. text-embedding-3-small) |
input | string or array | Yes | Text to embed; batch arrays may hold up to 2048 items (a flat token array counts as a single input) |
encoding_format | string | No | float (default) or base64 |
dimensions | integer | No | Output dimensions (v3 models only) |
user | string | No | End-user identifier, forwarded to the provider |
Any additional parameters are forwarded to the provider unchanged, so future OpenAI options work without a GhostAI update. The provider's response and error codes are returned as-is.
Billing: each embeddings request costs 1 credit, regardless of batch size -- batch your chunks. Requests are rejected with insufficient_quota (HTTP 429) when your subscription's credit limit is reached.
Streaming
Enable streaming with "stream": true in your request:
bash
curl https://your-ghostai-instance.com/v1/chat/completions \
-H "Authorization: Bearer gst_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello"}],
"stream": true
}'Response is Server-Sent Events (SSE):
data: {"id":"chatcmpl-ghost-abc","object":"chat.completion.chunk","created":1706745600,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
data: {"id":"chatcmpl-ghost-abc","object":"chat.completion.chunk","created":1706745600,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
data: {"id":"chatcmpl-ghost-abc","object":"chat.completion.chunk","created":1706745600,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}
data: {"id":"chatcmpl-ghost-abc","object":"chat.completion.chunk","created":1706745600,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]Endpoint Summary
| Endpoint | Method | Format | Primary Use |
|---|---|---|---|
/v1/chat/completions | POST | Chat Completions | Chat, planning, code generation |
/v1/completions | POST | Legacy Completions | Autocomplete, FIM |
/v1/responses | POST | Responses API | GPT-5/o-series, newer SDKs |
/v1/models | GET | Model List | Discover available models |
/v1/models/{id} | GET | Model Info | Model details |
/v1/embeddings | POST | Embeddings | Vector embeddings for IDE indexing / RAG (pass-through, no PII protection) |
/v1/tokenize | POST | Tokenize | Replace PII with tokens |
/v1/detokenize | POST | Detokenize | Restore original PII |
/v1/messages | POST | Anthropic Messages | Claude models (docs) |
Integration Examples
OpenWebUI
- Go to Settings → Connections → OpenAI API
- Set Base URL:
https://your-ghostai-instance.com/v1 - Set API Key:
gst_your_api_key_here - Save and start chatting with PII protection
n8n
- Add an OpenAI node to your workflow
- Create new credentials:
- API Key:
gst_your_api_key_here - Base URL:
https://your-ghostai-instance.com/v1
- API Key:
- Configure the node and execute
OpenClaw
Add GhostAI as a custom provider in openclaw.json:
json
{
"models": {
"providers": {
"ghostclaw": {
"api": "openai-completions",
"baseUrl": "https://your-ghostai-instance.com/v1",
"apiKey": "${GHOSTAI_API_KEY}",
"models": ["openai/gpt-4o", "openai/gpt-4o-mini", "anthropic/claude-3.5-sonnet"]
}
}
}
}Or install the GhostClaw plugin for dynamic model catalog and slash commands:
bash
openclaw plugins install ghostclawLangChain (Python)
python
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
base_url="https://your-ghostai-instance.com/v1",
api_key="gst_your_api_key_here",
model="openai/gpt-4o-mini"
)
# PII is automatically protected
response = llm.invoke("My email is john@example.com. Send me a reminder.")
print(response.content)OpenAI Python SDK
python
from openai import OpenAI
client = OpenAI(
base_url="https://your-ghostai-instance.com/v1",
api_key="gst_your_api_key_here"
)
response = client.chat.completions.create(
model="openai/gpt-4o-mini",
messages=[
{"role": "user", "content": "My phone is 555-123-4567. Call me later."}
]
)
print(response.choices[0].message.content)
# PII was protected before reaching the LLM
print(f"PII items protected: {response.ghost_pii_detected}")OpenAI JavaScript SDK
javascript
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://your-ghostai-instance.com/v1',
apiKey: 'gst_your_api_key_here',
});
const response = await client.chat.completions.create({
model: 'openai/gpt-4o-mini',
messages: [
{ role: 'user', content: 'My credit card is 4111-1111-1111-1111.' }
],
});
console.log(response.choices[0].message.content);cURL
bash
# Non-streaming
curl https://your-ghostai-instance.com/v1/chat/completions \
-H "Authorization: Bearer gst_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello, world!"}]
}'
# Streaming
curl https://your-ghostai-instance.com/v1/chat/completions \
-H "Authorization: Bearer gst_your_api_key_here" \
-H "Content-Type: application/json" \
-N \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "Tell me a story"}],
"stream": true
}'PII Protection Flow
All endpoints (/v1/chat/completions, /v1/completions, /v1/responses) share the same protection pipeline:
- Client sends request to GhostAI in the appropriate API format
- GhostAI detects PII and secrets in user messages (SSN, emails, phones, API keys, etc.)
- PII is replaced with tokens (e.g.,
[EMAIL_abc123]) - Sanitized request is forwarded to the configured LLM provider
- Response is detokenized (tokens replaced with original values)
- Response is scanned for secrets (if
scan_responsesis enabled) - API-format response returned to client
The LLM never sees the actual PII -- only the tokens. This applies to both streaming and non-streaming responses.
The exception is /v1/embeddings: embedding vectors must be computed from the original text to be useful, so that endpoint forwards input verbatim and is clearly marked as pass-through above.
Error Handling
Errors follow OpenAI's error format:
json
{
"error": {
"message": "Invalid API key",
"type": "invalid_api_key",
"param": null,
"code": "invalid_api_key"
}
}Common Errors
| Code | HTTP | Description |
|---|---|---|
invalid_api_key | 401 | API key is invalid or malformed |
model_not_found | 404 | Requested model doesn't exist |
model_not_allowed | 403 | Model is blocked by your account's model allowlist |
feature_not_available | 403 | Endpoint is disabled for your plan (e.g. embeddings_api) |
rate_limited | 429 | Too many requests |
insufficient_quota | 429 | Monthly credit limit reached (metered endpoints) |
llm_error | 400 | Error from upstream LLM provider |
Rate Limits
API keys have configurable rate limits:
| Tier | Requests/minute |
|---|---|
| Starter | 60 |
| Personal | 120 |
| Team | 200 |
| Business | 300 |
| Enterprise | Unlimited |
Model Access Configuration
GhostAI supports a 5-tier model access hierarchy. Each tier can only restrict models, not expand access from higher tiers.
Configuration Hierarchy
- Cloud (Platform) - System-wide defaults and provider filtering
- Tenant (Organization) - Organization-level restrictions
- Admin - Admin-enforced policies
- User - Personal preferences and restrictions
- API Key - Per-key model restrictions
Configuration Options
| Setting | Cloud | Tenant | User | API Key |
|---|---|---|---|---|
allowed_providers | ✅ | ✅ | - | - |
blocked_providers | ✅ | ✅ | - | - |
allowed_models | ✅ | ✅ | ✅ | ✅ |
blocked_models | ✅ | ✅ | ✅ | ✅ |
max_models_shown | ✅ | ✅ | - | - |
show_free_models | ✅ | ✅ | ✅ | - |
show_beta_models | ✅ | ✅ | - | - |
favorite_models | - | - | ✅ | - |
default_model | - | - | ✅ | - |
model_rate_limits | - | - | - | ✅ |
API Endpoints
bash
# Get user's model config
GET /api/settings/model-config/user
# Update user's model config
PUT /api/settings/model-config/user
{
"favorite_models": ["openai/gpt-4o", "anthropic/claude-3.5-sonnet"],
"default_model": "openai/gpt-4o-mini",
"blocked_models": ["openai/gpt-3.5-turbo"]
}
# Get organization's model config (admin only)
GET /api/settings/model-config/organization
# Update organization's model config (admin only)
PUT /api/settings/model-config/organization
{
"allowed_providers": ["openai/", "anthropic/"],
"blocked_models": ["openai/gpt-3.5-turbo"],
"max_models_shown": 50,
"show_free_models": false
}
# Get API key's model config
GET /api/settings/model-config/api-key/{key_id}
# Update API key's model config
PUT /api/settings/model-config/api-key/{key_id}
{
"allowed_models": ["openai/gpt-4o-mini", "openai/gpt-4o"],
"model_rate_limits": {"openai/gpt-4o": 10}
}Example: Restrict API Key to Specific Models
bash
# Create an API key restricted to only GPT-4o models
curl -X PUT https://ghostai/api/settings/model-config/api-key/key_abc123 \
-H "Authorization: Bearer gst_admin_key" \
-H "Content-Type: application/json" \
-d '{
"allowed_models": ["openai/gpt-4o", "openai/gpt-4o-mini"]
}'When this API key calls /v1/models, it will only see those 2 models.
GhostAI Response Extensions
GhostAI adds these fields to standard OpenAI responses:
| Field | Type | Description |
|---|---|---|
ghost_pii_detected | integer | Number of PII items that were protected |
ghost_session_id | string | Session ID for PII token tracking |
These fields are optional and can be ignored by standard OpenAI clients.