blackbox-sdk

Official Blackbox SDK for logging AI interactions. Super simple, Mixpanel-style API.

Installation

npm install blackbox-sdk

Quick Start

Step 1: Get Your API Key

1. Log into your Blackbox dashboard
2. Go to Settings → API Keys
3. Click Create API Key
4. Copy the key immediately - it's shown only once!

Step 2: Initialize (Optional)

The SDK auto-initializes from environment variables, but you can also initialize manually:

import { blackbox } from 'blackbox-sdk';

// Option 1: Set environment variable (auto-initializes)
// BLACKBOX_API_KEY=bb_live_sk_...

// Option 2: Initialize manually
blackbox.init({
  apiKey: process.env.BLACKBOX_API_KEY!
});

Step 3: Log Interactions

import { blackbox } from 'blackbox-sdk';

// After your AI generates a response
blackbox.log({
  context: 'OCD', // Can be any string: "OCD", "ADHD", "anxiety", "depression", "therapy", etc.
  surface: 'chat',
  prompt: userPrompt,
  response: aiResponse,
  meta: { model: 'gpt-5', temperature: 0.7 }
});

That's it! Fire-and-forget, won't block your app.

API

blackbox.init(config?)

Initialize the SDK (optional - auto-initializes from env vars).

blackbox.init({
  apiKey: 'bb_live_sk_...',
  baseUrl: 'https://blackbox-app.fly.dev' // Optional, defaults to production
});

blackbox.log(params)

Log an AI interaction.

Required fields:

• context: string - Any context string (e.g., "OCD", "ADHD", "anxiety", "depression", "therapy", etc.)
• surface: string - Interaction surface (e.g., "chat", "voice", "email")
• prompt: string - User's input text
• response: string - AI's response text

Optional fields:

• system_prompt: string - System prompt used by the AI
• user_id: string - Anonymized user identifier (see privacy section)
• city: string - User's city (auto-detected if not provided)
• country: string - User's country code (auto-detected if not provided)
• agent: string - Action or agent name
• meta: object - Additional metadata (model, temperature, etc.)
• capture_mode: 'metadata' | 'full_input' - Capture mode (default: 'metadata'). See Full Input Capture section.

Environment Variables

• BLACKBOX_API_KEY - Your API key (format: bb_live_sk_... or bb_test_sk_...)
• BLACKBOX_BASE_URL - Your blackbox server URL (default: https://blackbox-app.fly.dev)
• NEXT_PUBLIC_BLACKBOX_API_KEY - For client-side usage in Next.js
• NEXT_PUBLIC_BLACKBOX_BASE_URL - For client-side usage in Next.js

Full Input Capture

By default, Blackbox stores only metadata (keywords, signals, etc.) and never stores full user prompts or AI responses. This protects user privacy while still enabling powerful analytics.

However, for debugging specific issues, you can optionally enable full input capture for individual requests. This stores the full input/output (with PII/secrets redacted) for a limited time.

When to Use Full Input

Use capture_mode: 'full_input' only when:

• User reports an issue (e.g., thumbs down, error report)
• Debugging a specific failure (e.g., timeout, unexpected response)
• Temporary debug window (e.g., during development or troubleshooting)
• User explicitly opts in (e.g., "help improve" feature)

When NOT to Use Full Input

The default metadata-only mode provides all the analytics you need for most use cases. Only use full_input when you specifically need to see the exact prompt/response for debugging. Don't use it for all requests by default.

How It Works

// Normal mode (default): metadata only
blackbox.log({
  context: 'OCD',
  surface: 'chat',
  prompt: userPrompt,
  response: aiResponse,
  // capture_mode defaults to 'metadata'
});

// Full input mode: stores full prompt/response for debugging
// Use when you need to see the exact prompt/response for debugging
blackbox.log({
  context: 'OCD',
  surface: 'chat',
  prompt: userPrompt,
  response: aiResponse,
  capture_mode: 'full_input', // Enable full capture
});

Security & Privacy

When capture_mode: 'full_input' is used:

1. PII Redaction: Emails and phone numbers are automatically redacted
2. Secret Detection: API keys, tokens, and secrets are detected and hard-blocked (capture is rejected if secrets are found)
3. TTL: Captures automatically expire after 14 days (configurable)
4. Access Control: Only workspace admins/owners can view debug captures
5. Access Logging: All access attempts are logged for audit

Accessing Debug Captures

Debug captures can be accessed via the admin API endpoint (requires admin/owner role):

GET /api/v1/debug-captures/{capture_id}?reason=debugging

Best Practices

• ✅ Use full_input for specific user-reported issues
• ✅ Use full_input for temporary debugging windows
• ✅ Use full_input when user explicitly opts in (e.g., "help improve" feature)
• The default metadata-only mode provides all the analytics you need for most use cases
• ❌ Don't store secrets in prompts (they'll be blocked anyway)

Privacy: User ID Anonymization

⚠️ IMPORTANT: Always anonymize user IDs before sending to blackbox.

Never send real user identifiers (emails, usernames, database IDs) directly. Use a one-way hash instead.

import crypto from 'crypto';
import { blackbox } from '@blackbox/blackbox-sdk';

function anonymizeUserId(userId: string, salt: string): string {
  return crypto
    .createHash('sha256')
    .update(userId + salt)
    .digest('hex')
    .substring(0, 16);
}

const SALT = process.env.BLACKBOX_USER_SALT || 'your-secret-salt';
const anonymizedId = anonymizeUserId(realUserId, SALT);

blackbox.log({
  context: 'OCD',
  surface: 'chat',
  prompt: userPrompt,
  response: aiResponse,
  user_id: anonymizedId,
  meta: { model: 'gpt-5' }
});

License

MIT