Skip to content

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

Authentication ​

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_here

Endpoints ​

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 ​

ParameterTypeRequiredDescription
modelstringYesModel ID (e.g., gpt-4o-mini, openai/gpt-4o-mini)
messagesarrayYesArray of message objects
temperaturenumberNoSampling temperature (0-2, default: 1.0)
top_pnumberNoNucleus sampling (0-1, default: 1.0)
max_tokensintegerNoMaximum tokens in response
streambooleanNoEnable streaming (default: false)
stopstring/arrayNoStop sequences
presence_penaltynumberNoPresence penalty (-2 to 2)
frequency_penaltynumberNoFrequency penalty (-2 to 2)

GhostAI-Specific Parameters ​

ParameterTypeDescription
ghost_session_idstringSession ID for PII token tracking (optional)
ghost_detokenizebooleanSet 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 ​

ParameterTypeRequiredDescription
modelstringYesModel ID (e.g., gpt-4o-mini, openai/gpt-4o-mini)
promptstring or arrayYesText to complete
max_tokensintegerNoMaximum tokens to generate (default: 512)
temperaturenumberNoSampling temperature (0-2, default: 1.0)
stopstring/arrayNoStop sequences
suffixstringNoSuffix for fill-in-the-middle (FIM) completion
streambooleanNoEnable 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 ​

ParameterTypeRequiredDescription
modelstringYesModel ID
inputstring or arrayYesPrompt text or array of message objects
instructionsstringNoSystem-level instructions
max_output_tokensintegerNoMaximum tokens in response
temperaturenumberNoSampling temperature (0-2)
streambooleanNoEnable 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 ​

ParameterTypeRequiredDescription
modelstringYesEmbedding model ID (e.g. text-embedding-3-small)
inputstring or arrayYesText to embed; batch arrays may hold up to 2048 items (a flat token array counts as a single input)
encoding_formatstringNofloat (default) or base64
dimensionsintegerNoOutput dimensions (v3 models only)
userstringNoEnd-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 ​

EndpointMethodFormatPrimary Use
/v1/chat/completionsPOSTChat CompletionsChat, planning, code generation
/v1/completionsPOSTLegacy CompletionsAutocomplete, FIM
/v1/responsesPOSTResponses APIGPT-5/o-series, newer SDKs
/v1/modelsGETModel ListDiscover available models
/v1/models/{id}GETModel InfoModel details
/v1/embeddingsPOSTEmbeddingsVector embeddings for IDE indexing / RAG (pass-through, no PII protection)
/v1/tokenizePOSTTokenizeReplace PII with tokens
/v1/detokenizePOSTDetokenizeRestore original PII
/v1/messagesPOSTAnthropic MessagesClaude models (docs)

Integration Examples ​

OpenWebUI ​

  1. Go to Settings → Connections → OpenAI API
  2. Set Base URL: https://your-ghostai-instance.com/v1
  3. Set API Key: gst_your_api_key_here
  4. Save and start chatting with PII protection

n8n ​

  1. Add an OpenAI node to your workflow
  2. Create new credentials:
    • API Key: gst_your_api_key_here
    • Base URL: https://your-ghostai-instance.com/v1
  3. 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 ghostclaw

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

  1. Client sends request to GhostAI in the appropriate API format
  2. GhostAI detects PII and secrets in user messages (SSN, emails, phones, API keys, etc.)
  3. PII is replaced with tokens (e.g., [EMAIL_abc123])
  4. Sanitized request is forwarded to the configured LLM provider
  5. Response is detokenized (tokens replaced with original values)
  6. Response is scanned for secrets (if scan_responses is enabled)
  7. 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 ​

CodeHTTPDescription
invalid_api_key401API key is invalid or malformed
model_not_found404Requested model doesn't exist
model_not_allowed403Model is blocked by your account's model allowlist
feature_not_available403Endpoint is disabled for your plan (e.g. embeddings_api)
rate_limited429Too many requests
insufficient_quota429Monthly credit limit reached (metered endpoints)
llm_error400Error from upstream LLM provider

Rate Limits ​

API keys have configurable rate limits:

TierRequests/minute
Starter60
Personal120
Team200
Business300
EnterpriseUnlimited

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 ​

  1. Cloud (Platform) - System-wide defaults and provider filtering
  2. Tenant (Organization) - Organization-level restrictions
  3. Admin - Admin-enforced policies
  4. User - Personal preferences and restrictions
  5. API Key - Per-key model restrictions

Configuration Options ​

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

FieldTypeDescription
ghost_pii_detectedintegerNumber of PII items that were protected
ghost_session_idstringSession ID for PII token tracking

These fields are optional and can be ignored by standard OpenAI clients.

SOC 2 Type II Certified | BAA Available | HIPAA-Ready