Appearance
API Reference
Complete reference for the GhostAI REST API.
Overview
The GhostAI API provides programmatic access to all features:
- Chat with AI while protecting PII
- Detect sensitive data in text
- Manage sessions and tokens
- Access audit logs and reports
Base URL
Production: https://api.ghostai.com/v1
Development: http://localhost:8000/apiAuthentication
All API requests require authentication via Bearer token:
bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.ghostai.com/v1/endpointGet your API token from Settings → API Keys in the dashboard.
CLI
For terminal-based access, install the ghostai CLI:
bash
pip install ghostai-cli
export GHOSTAI_API_KEY="gst_your_key_here"
ghostai scan "John Smith, SSN 123-45-6789"
ghostai memory search "user preferences"
ghostai memory import memories.json
ghostai statusSee ghostai --help for all commands.
Quick Start
Send a Chat Message
bash
curl -X POST https://api.ghostai.com/v1/chat \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"message": "My SSN is 123-45-6789. Help me with taxes.",
"session_id": "optional-session-id"
}'Response:
json
{
"response": "Based on your SSN 123-45-6789, here are tax recommendations...",
"session_id": "sess_abc123",
"pii_detected": 1,
"entities": [
{
"type": "US_SSN",
"token": "[US_SSN_x1y2z3]",
"confidence": 0.99
}
]
}Detect PII Only
bash
curl -X POST https://api.ghostai.com/v1/detect \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"text": "Contact john@example.com or call (555) 123-4567"
}'Response:
json
{
"entities": [
{
"type": "EMAIL_ADDRESS",
"text": "john@example.com",
"start": 8,
"end": 24,
"confidence": 0.98
},
{
"type": "PHONE_NUMBER",
"text": "(555) 123-4567",
"start": 33,
"end": 47,
"confidence": 0.95
}
],
"pii_count": 2
}Endpoints
| Endpoint | Method | Description |
|---|---|---|
| /chat | POST | Send message with PII protection |
| /detect | POST | Detect PII without chat |
| /tokenize | POST | Tokenize text |
| /detokenize | POST | Restore original values |
| /sessions | GET | List sessions |
| /export | POST | Export reports |
| /webhooks | POST | Event notifications |
| SIEM Integration | GET/POST/PUT/DELETE | SIEM preset management, integration CRUD, event catalog, health monitoring, pull API |
File Intelligence Endpoints
| Endpoint | Method | Description |
|---|---|---|
| /files/upload | POST | Upload file (up to 150 MB, gzip support) |
| /files/{id}/scan | POST | PII scan with optional sample_rows for progressive scanning |
| /files/{id} | GET | File metadata including is_indexed and chunk_count |
| /files/limits | GET | Current upload size limits |
Files over 1 MB are automatically RAG-indexed in the background. RAG configuration (hybrid search, HNSW, PII cache, streaming, embedding device) is managed via the Admin Dashboard or config settings.
Team & Invitation APIs
| Endpoint | Method | Description |
|---|---|---|
/api/organizations/{id}/members | POST | Invite a member |
/api/organizations/{id}/members/{mid} | DELETE | Cancel invite or remove member |
/api/organizations/{id}/leave | DELETE | Permanently leave the organization as the authenticated user |
/api/organizations/{id}/members/{mid}/resend | POST | Resend invitation |
/api/organizations/{id}/members/{mid}/offboard | POST | Offboard user |
/api/organizations/{id}/invites/accept | POST | Accept invitation |
/api/organizations/{id}/seat-info | GET | Seat usage and limits |
/api/organizations/{id}/allowed-domains | GET/POST | Domain allowlist |
/api/organizations/{id}/invite-links | GET/POST | Shareable invite links |
/api/organizations/{id}/join | POST | Join via invite link |
/api/organizations/{id}/settings | GET/PUT | Welcome message settings |
/api/organizations/{id}/setup-progress | GET | Setup checklist |
SCIM 2.0 Provisioning API
| Endpoint | Method | Description |
|---|---|---|
/scim/v2/Users | GET/POST | List or provision users |
/scim/v2/Users/{id} | GET/PATCH/DELETE | Manage provisioned user |
/api/organizations/{id}/scim-tokens | GET/POST/DELETE | SCIM token management |
See Authentication → SCIM for setup details.
OpenAI-Compatible API
GhostAI provides an OpenAI-compatible API for drop-in replacement in third-party tools and AI coding assistants:
| Endpoint | Method | Description |
|---|---|---|
| /v1/chat/completions | POST | Chat with PII protection (OpenAI format) |
| /v1/completions | POST | Legacy completions for autocomplete/FIM |
| /v1/responses | POST | OpenAI Responses API (GPT-5/o-series) |
| /v1/models | GET | List available models |
| /v1/tokenize | POST | Tokenize text (replace PII with tokens) |
| /v1/detokenize | POST | Detokenize text (restore original PII) |
Anthropic-Compatible API
| Endpoint | Method | Description |
|---|---|---|
| /v1/messages | POST | Anthropic Messages API with PII/secrets protection |
Compatible AI Coding Tools
GhostAI works as a drop-in proxy for popular AI coding tools. See the AI Tool Setup Guide for configuration details.
| Tool | Protocol |
|---|---|
| Continue | OpenAI or Anthropic |
| Cursor | OpenAI |
| Cline | OpenAI or Anthropic |
| Claude Code | Anthropic |
| Aider | OpenAI or Anthropic |
| Windsurf | OpenAI |
| Google Antigravity | OpenAI |
| OpenClaw | OpenAI |
Also works with OpenWebUI, n8n, LangChain, and any OpenAI/Anthropic SDK client.
MCP Server
GhostAI provides a Model Context Protocol (MCP) server for AI assistants and automation tools:
| Tool | Description |
|---|---|
ghostai_detect_pii | Detect PII in text |
ghostai_sanitize | Replace PII with tokens |
ghostai_restore | Restore original values |
ghostai_tokenize | Tokenize text (alias for sanitize) |
ghostai_detokenize | Detokenize text (alias for restore) |
ghostai_chat | Protected chat with automatic PII handling |
ghostai_scan_file | Scan files for PII |
ghostai_list_sessions | List active sessions |
Works with Cursor IDE, Claude Desktop, n8n, and any MCP-compatible client.
Rate Limits
| Tier | Requests/min | Burst |
|---|---|---|
| Starter | 10 | 20 |
| Personal | 60 | 120 |
| Team | 120 | 240 |
| Business | 300 | 600 |
| Enterprise | Custom | Custom |
Rate limit headers:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1699488000Error Handling
Error Response Format
json
{
"error": {
"code": "invalid_request",
"message": "The request body is invalid",
"details": {
"field": "message",
"issue": "required"
}
}
}Error Codes
| Code | HTTP | Description |
|---|---|---|
unauthorized | 401 | Invalid or missing token |
forbidden | 403 | Insufficient permissions |
not_found | 404 | Resource not found |
rate_limited | 429 | Too many requests |
invalid_request | 400 | Bad request format |
server_error | 500 | Internal error |
Pagination
List endpoints support pagination:
bash
curl "https://api.ghostai.com/v1/sessions?page=1&limit=20"Response includes pagination info:
json
{
"data": [...],
"pagination": {
"page": 1,
"limit": 20,
"total": 150,
"pages": 8
}
}Versioning
The API is versioned via URL path:
v1- Current stable versionv2- (Coming soon)
We maintain backward compatibility within major versions.
SDKs
Official SDKs:
Content Library API
Protected internal document sharing with granular access control and full audit logging. All endpoints are prefixed with /api/content-library.
Browse & Read
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/content-library/access-check | GET | User | Check if user has any content library access |
/api/content-library/categories | GET | content_library:read | List accessible categories with item counts |
/api/content-library/items | GET | content_library:read | List items (optional category, search filters) |
/api/content-library/items/{id} | GET | content_library:read | Get item content (rendered) |
/api/content-library/items/{id}/raw | GET | content_library:read | Download raw file |
/api/content-library/items/{id}/pdf | GET | content_library:read | Export as watermarked PDF |
/api/content-library/search | GET | content_library:read | Hybrid BM25 + semantic search |
/api/content-library/recommended | GET | content_library:read | Profile-based recommendations |
/api/content-library/recent | GET | content_library:read | Recently viewed documents |
/api/content-library/bookmarks | GET | content_library:read | List bookmarked items |
/api/content-library/items/{id}/bookmark | POST | content_library:read | Toggle bookmark |
/api/content-library/items/{id}/related | GET | content_library:read | Related documents via embedding similarity |
Version History
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/content-library/items/{id}/versions | GET | content_library:read | List version history |
/api/content-library/items/{id}/versions/{v} | GET | content_library:read | Get version content |
/api/content-library/items/{id}/diff | GET | content_library:read | Unified diff (from, to params) |
Feedback, Acknowledgments & Collections
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/content-library/items/{id}/feedback | POST | content_library:read | Submit feedback |
/api/content-library/items/{id}/acknowledge | POST | content_library:read | Acknowledge document |
/api/content-library/items/{id}/acknowledgments | GET | content_library:manage | List acknowledgments |
/api/content-library/feedback | GET | content_library:audit | List all feedback |
/api/content-library/feedback/{id} | DELETE | content_library:manage | Delete feedback |
/api/content-library/collections | GET/POST | content_library:read | List or create collections |
/api/content-library/collections/{id} | PATCH/DELETE | content_library:read | Update or delete collection |
/api/content-library/collections/{id}/items | POST | content_library:read | Add items to collection |
/api/content-library/collections/{col}/items/{item} | DELETE | content_library:read | Remove item from collection |
Access Requests & Grant Management
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/content-library/access-requests | POST | content_library:read | Submit access request |
/api/content-library/access-requests | GET | content_library:manage | List all requests |
/api/content-library/access-requests/{id} | PATCH | content_library:manage | Approve or deny |
/api/content-library/grants | GET/POST | content_library:manage | List or create grants |
/api/content-library/grants/bulk | POST | content_library:manage | Bulk grant with role template |
/api/content-library/grants/{id} | DELETE | content_library:manage | Revoke grant |
/api/content-library/grant-templates | GET | content_library:manage | List role-based templates |
Admin & Analytics
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/content-library/scan | POST | Platform Admin | Re-index content from disk |
/api/content-library/analytics | GET | content_library:audit | Usage analytics |
/api/content-library/stale | GET | content_library:audit | Stale content detection |
/api/content-library/audit | GET | content_library:audit | Audit log |
/api/content-library/items/{id} | PATCH | content_library:manage | Update item flags |
See Content Library feature docs for full details on the access control model, search, and configuration.
Referral API
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/referral/code | GET | User | Get or create your referral code and link |
/api/referral/stats | GET | User | Get referral dashboard stats |
/api/referral/leaderboard | GET | User | Get top referrers leaderboard |
/api/referral/rewards | GET | User | Get your referral rewards |
/api/referral/share-links | GET | User | Get pre-filled social share URLs |
/api/referral/resolve/{code} | GET | Public | Resolve a referral/promo code |
/api/referral/war-room | GET | User | Get aggregated launch metrics |
/api/referral/admin/promo-codes | GET | Admin | List all promo codes |
/api/referral/admin/promo-codes | POST | Admin | Create a promo code |
/api/referral/admin/promo-codes/{id} | PUT | Admin | Update a promo code |
/api/referral/admin/overview | GET | Admin | Get referral program overview |
Support
- Documentation: docs.ghostai.com
- Email: dwessels@yahoo.com