Skip to content

Secrets API Reference ​

API endpoints for secrets detection, policy configuration, and audit.

IDE and agent traffic that should be scanned before it reaches an LLM is usually configured as a proxy to GhostAI’s OpenAI- or Anthropic-compatible endpoints, not through this REST API. Use Settings → Keys → Connect a tool in the app, or the AI tool setup guide, for step-by-step configuration.

POST /api/detect/secrets ​

Scan text for secrets (API keys, tokens, credentials, database URLs, private keys).

Request ​

POST /api/detect/secrets
Content-Type: application/json
Authorization: Bearer <token>  (optional)
json
{
  "text": "My API key is sk-proj-abc123xyz789... and DB url is postgres://user:secret@localhost/db",
  "filename": ".env"
}
FieldTypeRequiredDescription
textstringYesText to scan for secrets
filenamestringNoOptional filename for context (e.g., .env enables env parsing)

Response ​

json
{
  "secrets": [
    {
      "secret_type": "openai_key",
      "masked_value": "sk-p****xyz789",
      "start": 15,
      "end": 48,
      "line_number": 1,
      "confidence": 0.9,
      "severity": "high",
      "context": "My API key is sk-proj-abc123xyz789..."
    },
    {
      "secret_type": "database_url",
      "masked_value": "postg****ocalhost/db",
      "start": 55,
      "end": 85,
      "line_number": 1,
      "confidence": 0.95,
      "severity": "critical",
      "context": "DB url is postgres://user:secret@localhost/db"
    }
  ],
  "count": 2,
  "high_risk_count": 2
}
FieldTypeDescription
secretsarrayDetected secrets with masked values
countintegerTotal number of secrets found
high_risk_countintegerCount of high-confidence (≥0.90) secrets

POST /v1/messages (Anthropic Compat) ​

Anthropic Messages API endpoint compatible with Claude Code, Cline, Continue (Anthropic mode), and Aider. All user and system message content is scanned for secrets before forwarding to the model. Policy (warn/block/redact) and secret budget apply.

What's New

  • Response secrets scanning: When scan_responses is enabled, LLM responses are scanned for secrets and redacted before reaching the client.
  • Streaming detokenization: PII tokens in streamed responses are now properly restored, even when a token spans multiple SSE chunks.
  • Audit logging: All requests (including anonymous/unauthenticated) are now logged to the audit trail.

Request ​

POST /v1/messages
Content-Type: application/json
x-api-key: gst_<api_key>
anthropic-version: 2023-06-01
json
{
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Review this config: API_KEY=sk-abc123..."
    }
  ]
}

Response (success) ​

Secrets are redacted (in redact mode) before the request reaches Anthropic. The response includes GhostAI metadata when secrets were detected:

json
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "content": [...],
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "end_turn",
  "usage": {...}
}

Response headers may include x-ghost-secrets-detected when secrets were found and handled.

Response (blocked) ​

When policy is block and secrets are detected:

json
{
  "error": {
    "message": "Request blocked: 2 secret(s) detected. Remove secrets before sending to the AI provider.",
    "type": "secrets_blocked",
    "code": "secrets_detected"
  }
}

HTTP status: 400 Bad Request


GET /api/settings/secrets-policy ​

Get the current secrets protection policy and settings.

Request ​

GET /api/settings/secrets-policy
Authorization: Bearer <token>

Response ​

json
{
  "policy": "redact",
  "enabled": true,
  "scan_responses": true,
  "max_secrets_per_request": 5,
  "enable_entropy_detection": true,
  "entropy_threshold": 4.5,
  "description": "Detect secrets and replace them with reversible tokens before forwarding to the AI. Default and recommended mode."
}
FieldTypeDescription
policystringwarn, block, or redact
enabledbooleanWhether secrets detection is enabled
scan_responsesbooleanWhether to scan LLM responses for secrets
max_secrets_per_requestintegerSecret budget before policy escalation
enable_entropy_detectionbooleanEnable high-entropy string detection
entropy_thresholdnumberBits per character threshold (2.0–6.0)
descriptionstringHuman-readable policy description

PUT /api/settings/secrets-policy ​

Update secrets protection policy settings.

Request ​

PUT /api/settings/secrets-policy
Content-Type: application/json
Authorization: Bearer <token>
json
{
  "policy": "block",
  "enabled": true,
  "scan_responses": true,
  "max_secrets_per_request": 10,
  "enable_entropy_detection": true,
  "entropy_threshold": 4.5
}
FieldTypeRequiredDescription
policystringNowarn, block, or redact
enabledbooleanNoEnable/disable secrets detection
scan_responsesbooleanNoScan LLM responses
max_secrets_per_requestintegerNoMust be ≥ 1
enable_entropy_detectionbooleanNoEnable entropy detection
entropy_thresholdnumberNoMust be between 2.0 and 6.0

All fields are optional; only provided fields are updated.

Response ​

Same structure as GET response with updated values.

Validation Errors ​

  • max_secrets_per_request must be >= 1 — HTTP 422
  • entropy_threshold must be between 2.0 and 6.0 — HTTP 422

GET /api/secrets/audit ​

Paginated list of secret detection events.

Request ​

GET /api/secrets/audit?limit=50&offset=0
Authorization: Bearer <token>
QueryTypeDefaultDescription
limitinteger50Page size (1–500)
offsetinteger0Pagination offset

Response ​

json
{
  "items": [
    {
      "id": "det-001",
      "secret_type": "aws_access_key",
      "masked_value": "AKIA****abcd",
      "severity": "high",
      "source_tool": "cursor",
      "action": "blocked",
      "detected_at": "2025-03-11T14:30:00Z",
      "context": "AWS_ACCESS_KEY_ID=AKIA..."
    },
    {
      "id": "det-002",
      "secret_type": "github_token",
      "masked_value": "ghp_****xyz",
      "severity": "high",
      "source_tool": "cursor",
      "action": "warned",
      "detected_at": "2025-03-11T14:25:00Z",
      "context": "GITHUB_TOKEN=ghp_..."
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}
FieldTypeDescription
itemsarrayDetection records
totalintegerTotal count
limitintegerPage size
offsetintegerOffset used

GET /api/secrets/audit/summary ​

Aggregate statistics for secret detections.

Request ​

GET /api/secrets/audit/summary
Authorization: Bearer <token>

Response ​

json
{
  "total_detected": 15,
  "by_type": {
    "aws_access_key": 3,
    "github_token": 5,
    "openai_key": 4,
    "database_url": 2,
    "generic_api_key": 1
  },
  "by_tool": {
    "cursor": 8,
    "chat": 5,
    "claude_code": 2
  },
  "by_action": {
    "blocked": 6,
    "warned": 4,
    "redacted": 5
  }
}

GET /api/secrets/audit/rotation-needed ​

Secrets detected in warn mode that should be rotated (exposed but allowed through).

Request ​

GET /api/secrets/audit/rotation-needed
Authorization: Bearer <token>

Response ​

json
{
  "items": [
    {
      "id": "det-002",
      "secret_type": "github_token",
      "masked_value": "ghp_****xyz",
      "severity": "high",
      "source_tool": "cursor",
      "detected_at": "2025-03-11T14:25:00Z"
    }
  ],
  "total": 1
}

  • POST /v1/chat/completions — OpenAI-compatible chat; secrets protection applies to user messages. See OpenAI Compatible API.
  • POST /api/detect — PII detection (complementary to secrets). See Detection API.

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