Skip to content

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

Authentication ​

All API requests require authentication via Bearer token:

bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.ghostai.com/v1/endpoint

Get 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 status

See 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 ​

EndpointMethodDescription
/chatPOSTSend message with PII protection
/detectPOSTDetect PII without chat
/tokenizePOSTTokenize text
/detokenizePOSTRestore original values
/sessionsGETList sessions
/exportPOSTExport reports
/webhooksPOSTEvent notifications
SIEM IntegrationGET/POST/PUT/DELETESIEM preset management, integration CRUD, event catalog, health monitoring, pull API

File Intelligence Endpoints ​

EndpointMethodDescription
/files/uploadPOSTUpload file (up to 150 MB, gzip support)
/files/{id}/scanPOSTPII scan with optional sample_rows for progressive scanning
/files/{id}GETFile metadata including is_indexed and chunk_count
/files/limitsGETCurrent 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 ​

EndpointMethodDescription
/api/organizations/{id}/membersPOSTInvite a member
/api/organizations/{id}/members/{mid}DELETECancel invite or remove member
/api/organizations/{id}/leaveDELETEPermanently leave the organization as the authenticated user
/api/organizations/{id}/members/{mid}/resendPOSTResend invitation
/api/organizations/{id}/members/{mid}/offboardPOSTOffboard user
/api/organizations/{id}/invites/acceptPOSTAccept invitation
/api/organizations/{id}/seat-infoGETSeat usage and limits
/api/organizations/{id}/allowed-domainsGET/POSTDomain allowlist
/api/organizations/{id}/invite-linksGET/POSTShareable invite links
/api/organizations/{id}/joinPOSTJoin via invite link
/api/organizations/{id}/settingsGET/PUTWelcome message settings
/api/organizations/{id}/setup-progressGETSetup checklist

SCIM 2.0 Provisioning API ​

EndpointMethodDescription
/scim/v2/UsersGET/POSTList or provision users
/scim/v2/Users/{id}GET/PATCH/DELETEManage provisioned user
/api/organizations/{id}/scim-tokensGET/POST/DELETESCIM 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:

EndpointMethodDescription
/v1/chat/completionsPOSTChat with PII protection (OpenAI format)
/v1/completionsPOSTLegacy completions for autocomplete/FIM
/v1/responsesPOSTOpenAI Responses API (GPT-5/o-series)
/v1/modelsGETList available models
/v1/tokenizePOSTTokenize text (replace PII with tokens)
/v1/detokenizePOSTDetokenize text (restore original PII)

Anthropic-Compatible API ​

EndpointMethodDescription
/v1/messagesPOSTAnthropic 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.

ToolProtocol
ContinueOpenAI or Anthropic
CursorOpenAI
ClineOpenAI or Anthropic
Claude CodeAnthropic
AiderOpenAI or Anthropic
WindsurfOpenAI
Google AntigravityOpenAI
OpenClawOpenAI

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:

ToolDescription
ghostai_detect_piiDetect PII in text
ghostai_sanitizeReplace PII with tokens
ghostai_restoreRestore original values
ghostai_tokenizeTokenize text (alias for sanitize)
ghostai_detokenizeDetokenize text (alias for restore)
ghostai_chatProtected chat with automatic PII handling
ghostai_scan_fileScan files for PII
ghostai_list_sessionsList active sessions

Works with Cursor IDE, Claude Desktop, n8n, and any MCP-compatible client.

Rate Limits ​

TierRequests/minBurst
Starter1020
Personal60120
Team120240
Business300600
EnterpriseCustomCustom

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1699488000

Error Handling ​

Error Response Format ​

json
{
  "error": {
    "code": "invalid_request",
    "message": "The request body is invalid",
    "details": {
      "field": "message",
      "issue": "required"
    }
  }
}

Error Codes ​

CodeHTTPDescription
unauthorized401Invalid or missing token
forbidden403Insufficient permissions
not_found404Resource not found
rate_limited429Too many requests
invalid_request400Bad request format
server_error500Internal 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 version
  • v2 - (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 ​

EndpointMethodAuthDescription
/api/content-library/access-checkGETUserCheck if user has any content library access
/api/content-library/categoriesGETcontent_library:readList accessible categories with item counts
/api/content-library/itemsGETcontent_library:readList items (optional category, search filters)
/api/content-library/items/{id}GETcontent_library:readGet item content (rendered)
/api/content-library/items/{id}/rawGETcontent_library:readDownload raw file
/api/content-library/items/{id}/pdfGETcontent_library:readExport as watermarked PDF
/api/content-library/searchGETcontent_library:readHybrid BM25 + semantic search
/api/content-library/recommendedGETcontent_library:readProfile-based recommendations
/api/content-library/recentGETcontent_library:readRecently viewed documents
/api/content-library/bookmarksGETcontent_library:readList bookmarked items
/api/content-library/items/{id}/bookmarkPOSTcontent_library:readToggle bookmark
/api/content-library/items/{id}/relatedGETcontent_library:readRelated documents via embedding similarity

Version History ​

EndpointMethodAuthDescription
/api/content-library/items/{id}/versionsGETcontent_library:readList version history
/api/content-library/items/{id}/versions/{v}GETcontent_library:readGet version content
/api/content-library/items/{id}/diffGETcontent_library:readUnified diff (from, to params)

Feedback, Acknowledgments & Collections ​

EndpointMethodAuthDescription
/api/content-library/items/{id}/feedbackPOSTcontent_library:readSubmit feedback
/api/content-library/items/{id}/acknowledgePOSTcontent_library:readAcknowledge document
/api/content-library/items/{id}/acknowledgmentsGETcontent_library:manageList acknowledgments
/api/content-library/feedbackGETcontent_library:auditList all feedback
/api/content-library/feedback/{id}DELETEcontent_library:manageDelete feedback
/api/content-library/collectionsGET/POSTcontent_library:readList or create collections
/api/content-library/collections/{id}PATCH/DELETEcontent_library:readUpdate or delete collection
/api/content-library/collections/{id}/itemsPOSTcontent_library:readAdd items to collection
/api/content-library/collections/{col}/items/{item}DELETEcontent_library:readRemove item from collection

Access Requests & Grant Management ​

EndpointMethodAuthDescription
/api/content-library/access-requestsPOSTcontent_library:readSubmit access request
/api/content-library/access-requestsGETcontent_library:manageList all requests
/api/content-library/access-requests/{id}PATCHcontent_library:manageApprove or deny
/api/content-library/grantsGET/POSTcontent_library:manageList or create grants
/api/content-library/grants/bulkPOSTcontent_library:manageBulk grant with role template
/api/content-library/grants/{id}DELETEcontent_library:manageRevoke grant
/api/content-library/grant-templatesGETcontent_library:manageList role-based templates

Admin & Analytics ​

EndpointMethodAuthDescription
/api/content-library/scanPOSTPlatform AdminRe-index content from disk
/api/content-library/analyticsGETcontent_library:auditUsage analytics
/api/content-library/staleGETcontent_library:auditStale content detection
/api/content-library/auditGETcontent_library:auditAudit log
/api/content-library/items/{id}PATCHcontent_library:manageUpdate item flags

See Content Library feature docs for full details on the access control model, search, and configuration.

Referral API ​

EndpointMethodAuthDescription
/api/referral/codeGETUserGet or create your referral code and link
/api/referral/statsGETUserGet referral dashboard stats
/api/referral/leaderboardGETUserGet top referrers leaderboard
/api/referral/rewardsGETUserGet your referral rewards
/api/referral/share-linksGETUserGet pre-filled social share URLs
/api/referral/resolve/{code}GETPublicResolve a referral/promo code
/api/referral/war-roomGETUserGet aggregated launch metrics
/api/referral/admin/promo-codesGETAdminList all promo codes
/api/referral/admin/promo-codesPOSTAdminCreate a promo code
/api/referral/admin/promo-codes/{id}PUTAdminUpdate a promo code
/api/referral/admin/overviewGETAdminGet referral program overview

Support ​

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