provenby-api

Typed REST client for the ProvenBy API.

Zero dependencies. Works in Node 18+, Deno, Bun, Cloudflare Workers, and browsers.

Install

npm install provenby-api

Quickstart

import { ProvenByClient } from 'provenby-api';

const client = new ProvenByClient({
  apiKey: process.env.PROVENBY_KEY!,
});

// Search candidates
const { items } = await client.search({
  skills: ['TypeScript', 'React'],
  minScore: 100,
});

// Query a candidate — tiered (card → digest → full context)
const answers = await client.query(items[0].candidateId, [
  'What is their strongest technical area?',
  'Do they ship code?',
]);

// Create a role
const role = await client.createRole({
  title: 'Senior Backend Engineer',
  required_skills: [{ skill: 'TypeScript', minLevel: 'senior' }],
});

// Register a webhook
await client.registerWebhook(
  'https://yourapp.com/webhooks/provenby',
  ['query.approved', 'signal.received'],
  'your-hmac-secret',
);

Configuration

new ProvenByClient({
  apiKey: 'sk_provenby_...',           // required
  serverUrl: 'https://provenby.dev',   // optional — defaults to prod
});

Error handling

import { ProvenByError } from 'provenby-api';

try {
  await client.query('bad-id', ['?']);
} catch (err) {
  if (err instanceof ProvenByError) {
    console.error(`${err.status}: ${err.message}`);
    // 401 → check API key
    // 404 → candidate not found
    // 429 → rate limited — respect Retry-After
  }
}

Rate limits

Free tier: 10 queries/min + 30 searches/min. Paid tier: 50 queries/min.

All responses include X-RateLimit-Remaining and Retry-After headers.

Build from source

npm run build  # produces dist/index.{js,cjs,d.ts}

Links

• Interactive API reference
• OpenAPI spec
• Webhook handler example
• Full docs