Juicebox Hello World

Overview

Three examples: natural language people search, profile enrichment, and contact data from 800M+ profiles.

Instructions

Example 1: Natural Language Search

import { JuiceboxClient } from '@juicebox/sdk';
const client = new JuiceboxClient({ apiKey: process.env.JUICEBOX_API_KEY });

const results = await client.search({
  query: 'senior ML engineer at FAANG with PhD in Bay Area',
  limit: 10,
  filters: { experience_years: { min: 5 } }
});
results.profiles.forEach(p =>
  console.log(`${p.name} | ${p.title} at ${p.company} | ${p.location}`)
);

Example 2: Profile Enrichment

const enriched = await client.enrich({
  linkedin_url: 'https://linkedin.com/in/example',
  fields: ['skills', 'experience', 'education', 'contact']
});
console.log(`Skills: ${enriched.skills.join(', ')}`);
if (enriched.tech_profile?.github) {
  console.log(`GitHub: ${enriched.tech_profile.github.repos} repos`);
}

Example 3: Contact Data (Python)

results = client.search(query='PM fintech NYC', limit=5, include_contact=True)
for p in results.profiles:
    email = p.contact.email if p.contact else 'N/A'
    print(f"{p.name} | {p.title} | {email}")

Error Handling

Resources

• Search API
• PeopleGPT

Next Steps

Explore juicebox-sdk-patterns for production code.

Juicebox Incident Runbook

Overview

Incident response procedures for Juicebox AI analysis platform integration failures. Covers analysis timeouts, dataset corruption, quota exhaustion, and export failures. Juicebox powers AI-driven people search and candidate analysis, so incidents disrupt recruiting pipelines, talent intelligence workflows, and automated sourcing. Classify severity immediately using the matrix below and follow the corresponding playbook.

Severity Levels

Diagnostic Steps

# Check API health
curl -s -o /dev/null -w "HTTP %{http_code}\n" \
  -H "Authorization: Bearer $JUICEBOX_API_KEY" \
  https://api.juicebox.ai/v1/health

# Check account quota usage
curl -s -H "Authorization: Bearer $JUICEBOX_API_KEY" \
  https://api.juicebox.ai/v1/account/quota | jq '.used, .limit, .remaining'

# Test a minimal search request
curl -s -w "\nHTTP %{http_code}\n" \
  -H "Authorization: Bearer $JUICEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST https://api.juicebox.ai/v1/search \
  -d '{"query": "software engineer", "limit": 1}'

Incident Playbooks

API Outage

1. Confirm via health endpoint and status.juicebox.ai
2. Activate fallback mode — serve cached search results to active users
3. Pause any automated sourcing pipelines to avoid wasting quota on retries
4. Notify recruiting team that live search is temporarily unavailable
5. Monitor status page and resume operations once health check passes

Authentication Failure

1. Verify API key is set: echo $JUICEBOXAPIKEY | wc -c
2. Test with health endpoint (see diagnostics above)
3. If 401: API key may be revoked — regenerate in Juicebox dashboard
4. If 403: check account tier permissions for the requested endpoint
5. Deploy new key and verify search requests succeed

Data Sync Failure

1. Check if recent analysis results are returning stale or incomplete data
2. Verify export endpoints are responding — test a small CSV export

Juicebox Install & Auth

Overview

Set up Juicebox PeopleGPT API for AI-powered people search across 800M+ professional profiles.

Prerequisites

• Juicebox account at app.juicebox.ai
• API key from Dashboard > Settings > API Keys
• Node.js 18+ or Python 3.8+

Instructions

Step 1: Install SDK

npm install @juicebox/sdk
# or: pip install juicebox-sdk

Step 2: Configure Authentication

export JUICEBOX_API_KEY="jb_live_..."
echo 'JUICEBOX_API_KEY=jb_live_your-key' >> .env

Step 3: Verify Connection

import { JuiceboxClient } from '@juicebox/sdk';
const client = new JuiceboxClient({ apiKey: process.env.JUICEBOX_API_KEY });

const results = await client.search({ query: 'engineer', limit: 1 });
console.log(`Connected! ${results.total} profiles available`);

from juicebox import JuiceboxClient
client = JuiceboxClient(api_key=os.environ['JUICEBOX_API_KEY'])
results = client.search(query='engineer', limit=1)
print(f'Connected! {results.total} profiles')

Error Handling

Resources

• Juicebox Docs
• PeopleGPT

Next Steps

After auth, proceed to juicebox-hello-world.

Juicebox Local Dev Loop

Overview

Local development workflow for Juicebox AI-powered people analysis and recruiting API integration. Provides a fast feedback loop with mock profile search results and candidate enrichment data so you can build talent pipeline tools without consuming live API credits. Toggle between mock mode for rapid iteration and sandbox mode for validating against the real Juicebox API.

Environment Setup

cp .env.example .env
# Set your credentials:
# JUICEBOX_API_KEY=jb_live_xxxxxxxxxxxx
# JUICEBOX_BASE_URL=https://api.juicebox.work/v1
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express

Dev Server

// src/dev/server.ts
import express from "express";
import { createProxyMiddleware } from "http-proxy-middleware";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (!MOCK) {
  app.use("/v1", createProxyMiddleware({
    target: process.env.JUICEBOX_BASE_URL,
    changeOrigin: true,
    headers: { Authorization: `Bearer ${process.env.JUICEBOX_API_KEY}` },
  }));
} else {
  const { mountMockRoutes } = require("./mocks");
  mountMockRoutes(app);
}
app.listen(3004, () => console.log(`Juicebox dev server on :3004 [mock=${MOCK}]`));

Mock Mode

// src/dev/mocks.ts — realistic people search and enrichment responses
export function mountMockRoutes(app: any) {
  app.post("/v1/search", (req: any, res: any) => res.json({
    total: 150,
    profiles: [
      { id: "prof_1", name: "Jane Smith", title: "Senior Engineer", company: "Google", location: "San Francisco, CA", skills: ["TypeScript", "React", "GCP"] },
      { id: "prof_2", name: "Alex Chen", title: "Staff ML Engineer", company: "Meta", location: "New York, NY", skills: ["Python", "PyTorch", "MLOps"] },
    ],
  }));
  app.get("/v1/profiles/:id", (req: any, res: any) => res.json({
    id: req.params.id, name: "Jane Smith", title: "Senior Engineer", company: "Google",
    experience: [{ role: "Senior Engineer", company: "Google", years: 3 }],
    education: [{ school: "MIT", degree: "BS Computer Science" }],
  }));
  app.get("/v1/usage", (_req: any, res: any) => res.json({ creditsUsed: 12, creditsRemaining: 488, plan: "starter" }));
}

Testing Workflow

npm run dev:mock &                    # Start mock server in background
npm run test                          # Unit tests with vitest
npm run test -- --watch            

Juicebox Multi-Environment Setup

Overview

Juicebox AI analysis requires environment separation to enforce workspace isolation, control data access, and prevent accidental exports of sensitive datasets. Development works with sample datasets and strict result limits for fast iteration, staging connects to full production data but disables export functionality, and production enables all features with full export capabilities. Each environment uses isolated workspaces so analysis experiments in dev never affect production workspace state or user-facing reports.

Environment Configuration

const juiceboxConfig = (env: string) => ({
  development: {
    apiKey: process.env.JB_KEY_DEV!, baseUrl: "https://api.dev.juicebox.work/v1",
    workspaceId: process.env.JB_WORKSPACE_DEV!, resultLimit: 5, exportEnabled: false,
  },
  staging: {
    apiKey: process.env.JB_KEY_STG!, baseUrl: "https://api.staging.juicebox.work/v1",
    workspaceId: process.env.JB_WORKSPACE_STG!, resultLimit: 20, exportEnabled: false,
  },
  production: {
    apiKey: process.env.JB_KEY_PROD!, baseUrl: "https://api.juicebox.work/v1",
    workspaceId: process.env.JB_WORKSPACE_PROD!, resultLimit: 50, exportEnabled: true,
  },
}[env]);

Environment Files

# Per-env files: .env.development, .env.staging, .env.production
JB_KEY_{DEV|STG|PROD}=<api-key>
JB_WORKSPACE_{DEV|STG|PROD}=<workspace-id>
JB_BASE_URL=https://api.{dev.|staging.|""}juicebox.work/v1
JB_EXPORT_ENABLED={false|false|true}
JB_DATASET_SCOPE={sample|full|full}

Environment Validation

function validateJuiceboxEnv(env: string): void {
  const suffix = { development: "_DEV", staging: "_STG", production: "_PROD" }[env];
  const required = [`JB_KEY${suffix}`, `JB_WORKSPACE${suffix}`, "JB_BASE_URL"];
  const missing = required.filter((k) => !process.env[k]);
  if (missing.length) throw new Error(`Missing Juicebox vars for ${env}: ${missing.join(", ")}`);
}

Promotion Workflow

# 1. Run analysis queries against sample data in dev
curl -X POST "$JB_BASE_URL/analyze" \
  -H "Authorization: Bearer $JB_KEY_DEV" -d @test-query.json

# 2. Validate same queries against full dataset in staging (exports blocked)
curl -X POST "$JB_BASE_URL/analyze" \
  -H "Authorization: Bearer $JB_KEY_STG" -d @test-query.json | jq '.resultCount'

# 3. Verify workspace isolation — staging results don't appear in prod
curl "$JB_BASE_URL/workspaces/$JB_WORKSPACE_PROD/reports" \
  -H "Authorization: Bearer $JB_KEY_PROD" | jq 'length'

# 4. Deploy to production with export capabilities enabled
JB_EXPORT_ENABLED=true npm run deploy -- --env production
<

Juicebox Observability

Overview

Juicebox provides AI-powered people search and analysis where query performance, dataset ingestion rates, and quota consumption are the primary observability concerns. Monitor analysis completion times to ensure interactive UX, track ingestion pipeline health for data freshness, and watch quota usage to prevent mid-workflow cutoffs. Slow queries or failed ingestions degrade recruiter productivity and data accuracy.

Key Metrics

Instrumentation

async function trackJuiceboxCall(operation: string, fn: () => Promise<any>) {
  const start = Date.now();
  try {
    const result = await fn();
    metrics.histogram('juicebox.api.latency', Date.now() - start, { operation });
    metrics.increment('juicebox.api.calls', { operation, status: 'ok' });
    return result;
  } catch (err) {
    metrics.increment('juicebox.api.errors', { operation, error: err.code });
    throw err;
  }
}

Health Check Dashboard

async function juiceboxHealth(): Promise<Record<string, string>> {
  const searchP95 = await metrics.query('juicebox.api.latency', 'p95', '5m');
  const errorRate = await metrics.query('juicebox.api.error_rate', 'avg', '5m');
  const quota = await juiceboxAdmin.getQuotaUsage();
  return {
    search_latency: searchP95 < 2000 ? 'healthy' : 'slow',
    error_rate: errorRate < 0.01 ? 'healthy' : 'degraded',
    quota: quota.pct < 0.7 ? 'healthy' : 'at_risk',
  };
}

Alerting Rules

const alerts = [
  { metric: 'juicebox.search.latency_p95', condition: '> 5s', window: '10m', severity: 'warning' },
  { metric: 'juicebox.api.error_rate', condition: '> 0.05', window: '5m', severity: 'critical' },
  { metric: 'juicebox.quota.daily_pct', condition: '> 0.85', window: '1h', severity: 'warning' },
  { metric: 'juicebox.ingestion.rate', condition: '< 50/s', window: '15m', severity: 'critical' },

Juicebox Production Checklist

Overview

Juicebox provides AI-powered people search and analysis, enabling dataset creation, candidate discovery, and structured analysis across professional profiles. A production integration queries datasets, retrieves analysis results, and powers talent intelligence workflows. Failures mean missed candidates, stale analysis data, or quota exhaustion that blocks time-sensitive searches.

Authentication & Secrets

• [ ] JUICEBOXAPIKEY stored in secrets manager (not config files)
• [ ] API key scoped to production workspace only
• [ ] Key rotation schedule documented (90-day cycle)
• [ ] Separate credentials for dev/staging/prod environments
• [ ] Candidate data access restricted to authorized roles

API Integration

• [ ] Production base URL configured (https://api.juicebox.ai/v1)
• [ ] Rate limiting configured per plan tier
• [ ] Dataset creation and query endpoints tested end-to-end
• [ ] Analysis result pagination implemented for large datasets
• [ ] Search query optimization validated (precision vs recall tradeoffs)
• [ ] Bulk analysis requests batched to avoid rate limits
• [ ] Result caching configured for repeated queries

Error Handling & Resilience

• [ ] Circuit breaker configured for Juicebox API outages
• [ ] Retry with exponential backoff for 429/5xx responses
• [ ] Candidate data encrypted at rest in downstream storage
• [ ] GDPR/CCPA retention policy enforced on stored profiles
• [ ] Empty result sets handled gracefully (no silent failures)
• [ ] Quota exhaustion detected before critical searches fail

Monitoring & Alerting

• [ ] API latency tracked per endpoint (search, analysis, datasets)
• [ ] Error rate alerts set (threshold: >5% over 5 minutes)
• [ ] Quota usage monitored with alert at 80% consumption
• [ ] Analysis completion rate tracked for reliability metrics
• [ ] Daily digest of search volumes and result quality

Validation Script

async function checkJuiceboxReadiness(): Promise<void> {
  const checks: { name: string; pass: boolean; detail: string }[] = [];
  // API connectivity
  try {
    const res = await fetch('https://api.juicebox.ai/v1/search', {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.JUICEBOX_API_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ query: 'test', limit: 1 }),
    });
    checks.push({ name: 'Juicebox API', pass: res.ok, detail: res.ok ? 'Connected' : `HTTP ${res.status}` });
  } catch (e: any) { checks.push({ name: 'Juicebox API', pass: false, detail: e.message }); }
  // Credentials present
  checks.push({ nam