API Reference

All requests go to your BitDrip Policy Engine at http://your-host:3002/api/v1.

For local installations this is http://localhost:3002/api/v1.

Authentication

Generate an API key in Admin Dashboard → Settings → API Keys → Generate.

Authorization: Bearer YOUR_API_KEY

Endpoints

GET /health

Returns service health. No authentication required.

curl http://localhost:3002/health

{
  "status": "healthy",
  "timestamp": "2026-05-21T18:00:00.000Z",
  "version": "1.3.1",
  "services": {
    "database": { "status": "healthy", "latency": 3 },
    "cache":    { "status": "healthy", "latency": 2 }
  }
}

---

POST /api/v1/evaluate

Evaluate content against all active policies for your organisation.

POST /api/v1/evaluate
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request body:

{
  "content": "Text to evaluate",
  "context": {
    "service": "chatgpt",
    "userId": "user_abc"
  }
}

Response — violation detected:

{
  "action": "block",
  "violations": [
    {
      "category": "pii",
      "type": "ssn",
      "confidence": "high",
      "message": "Social Security Number detected"
    }
  ]
}

Response — clean:

{
  "action": "allow",
  "violations": []
}

---

Authentication endpoints

POST   /api/v1/auth/login
POST   /api/v1/auth/refresh
GET    /api/v1/auth/me
POST   /api/v1/auth/logout
GET    /api/v1/auth/api-keys
POST   /api/v1/auth/api-keys
DELETE /api/v1/auth/api-keys/:id
GET    /api/v1/auth/subscription/status

GET /api/v1/auth/api-keys

List all active API keys for the authenticated user. Returns prefix only — the full key is never retrievable after generation.

GET /api/v1/auth/api-keys
Authorization: Bearer YOUR_JWT

{
  "apiKeys": [
    {
      "id": "3f2a1b...",
      "name": "Workstation Tray App",
      "keyPrefix": "bdk_abc12345",
      "scopes": ["privacy_evaluate"],
      "active": true,
      "createdAt": "2026-06-01T09:00:00Z",
      "lastUsedAt": "2026-06-07T08:12:00Z",
      "expiresAt": null,
      "rateLimitPerHour": 1000
    }
  ]
}

POST /api/v1/auth/api-keys

Generate a new bdk_ API key. The full key is returned once — it cannot be retrieved again.

POST /api/v1/auth/api-keys
Authorization: Bearer YOUR_JWT
Content-Type: application/json

{
  "name": "Workstation Tray App",
  "scopes": ["privacy_evaluate"]
}

Available scopes: privacy_evaluate, read, audit_read, write.

Response:

{
  "apiKey": "bdk_abc12345.the_full_secret_token",
  "keyInfo": { "id": "...", "name": "Workstation Tray App", "keyPrefix": "bdk_abc12345", "..." },
  "warning": "Store this key securely. It will not be shown again."
}

DELETE /api/v1/auth/api-keys/:id

Revoke an API key immediately. Any client using the key will receive 401 on the next request.

---

Rules endpoints

Rules are scoped to an organisation. Replace :orgId with your organisation UUID.

GET    /api/v1/organizations/:orgId/rules
POST   /api/v1/organizations/:orgId/rules
PUT    /api/v1/organizations/:orgId/rules/:id
DELETE /api/v1/organizations/:orgId/rules/:id
POST   /api/v1/evaluate

POST /api/v1/organizations/:orgId/rules — regex rule

{
  "name": "Internal project codes",
  "matchType": "regex",
  "pattern": "PROJ-[0-9]{4,6}",
  "category": "proprietary",
  "confidence": "high",
  "action": "block",
  "priority": 50,
  "enabled": true
}

POST /api/v1/organizations/:orgId/rules — keyword list rule

Use matchType: "keyword_list" to match on exact terms (case-insensitive substring match). No pattern field needed.

{
  "name": "Project codenames",
  "matchType": "keyword_list",
  "keywords": ["ProjectAlpha", "Titan", "NexusCore"],
  "category": "proprietary",
  "confidence": "high",
  "action": "block",
  "priority": 50,
  "enabled": true
}

keywords accepts up to 500 strings, each up to 200 characters. The match is case-insensitive and substring-based — "titan" matches "Project Titan roadmap".

---

Policy endpoints (compliance profiles)

GET    /api/v1/policies
POST   /api/v1/policies
PUT    /api/v1/policies/:id
DELETE /api/v1/policies/:id

---

User endpoints

GET  /api/v1/users
POST /api/v1/users/invite
GET  /api/v1/users/:id

OpenAPI Spec

Full request/response schemas, field definitions, and interactive testing are available in the OpenAPI spec served by your running Policy Engine:

http://localhost:3002/api-docs

Rate Limits

Tier	Requests / minute
Community	60
Starter	300
Professional	1,000
Enterprise	Unlimited

Error Format

All errors follow this structure:

{
  "error": true,
  "code": "VALIDATION_ERROR",
  "message": "Human-readable description",
  "details": {}
}

Common error codes: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED.