@firsthandapi/sdk — FirstHandAPI TypeScript SDK

Official TypeScript SDK for FirstHandAPI — the human-in-the-loop (HITL) crowdsourced data collection API.

Post jobs via API. Real human workers capture photos, audio, video, and screen recordings. AI ensemble (Claude Vision + Whisper) auto-scores quality. Approved files delivered to your S3 folder. Use cases: UGC collection, ground truth for AI evaluation, LLM training data.

Installation

npm install @firsthandapi/sdk

Quick Start

import { FirstHandClient } from '@firsthandapi/sdk';

const client = new FirstHandClient({
  apiKey: 'fh_live_your_key_here',
});

// Post a content collection job
const job = await client.createJob({
  type: 'data_collection',
  description: 'Photos of grocery store shelf labels',
  files_needed: 100,
  accepted_formats: ['image/jpeg', 'image/png'],
  price_per_file_cents: 25,
});

// Wait for completion
const completed = await client.createJobAndWait({
  ...jobData,
}, 300); // wait up to 5 minutes

// Get approved files
const files = await client.getJobFiles(job.id);
files.data.forEach(file => {
  console.log(file.download_url);
});

Methods

Jobs

• createJob(body) — Post a new job
• getJob(id, options?) — Get job (supports long-poll)
• listJobs(params?) — List jobs
• cancelJob(id) — Cancel and refund
• getJobFiles(id) — Get approved files
• getJobSubmissions(id) — Get submissions
• createJobAndWait(body, maxWait) — Create and poll

Billing

• getCreditBalance() — Check balance
• listTransactions(params?) — Transaction history
• purchaseCredits(body) — Buy credits

Webhooks

• createWebhookEndpoint(body) — Register endpoint
• listWebhookEndpoints() — List endpoints
• verifyWebhookSignature(payload, signature, secret) — Verify webhook

API Keys

• createApiKey(body) — Create key
• listApiKeys() — List keys
• rotateApiKey(id) — Rotate key
• revokeApiKey(id) — Revoke key

Features

• Auto-retry with exponential backoff (429, 500+)
• Idempotency key generation
• Long-poll support
• TypeScript-native types

License

Proprietary