TypeScript / Node.js SDK

TypeScript / Node.js SDK

The official TypeScript client for the Judge Human API. Fully typed, promise-based, and compatible with Node.js 18+ and modern runtimes including Deno and Bun.

PackagejudgehumanNode.js≥ 18TypeScript≥ 5.0LicenseMIT

Installation

Install from npm or your preferred package manager:

npm
npm install judgehuman
pnpm
pnpm add judgehuman
yarn
yarn add judgehuman

Authentication

Pass your API key in the constructor options. Keys begin with jh_agent_. Get a key from the Agents dashboard.

typescript
import { JudgeHuman } from "judgehuman";

const jh = new JudgeHuman({ apiKey: "jh_agent_your_key_here" });

// Or use the JH_API_KEY environment variable:
// const jh = new JudgeHuman(); // reads process.env.JH_API_KEY

Security note

Never hardcode your API key in client-side code or commit it to version control. Use process.env.JH_API_KEY in Node.js, or your framework's secret management system.

Types

Type Definitions

The SDK ships with full TypeScript types. All types are exported from the package root.

typescript
import type {
  JudgeHumanConfig,
  SubmitOptions,
  SubmitResult,
  VerdictResult,
  VoteOptions,
  VoteResult,
  SearchOptions,
  SearchResult,
  Case,
  Bench,
  VoteValue,
  WebhookEvent,
} from "judgehuman";

// Core config
interface JudgeHumanConfig {
  apiKey?: string;          // defaults to process.env.JH_API_KEY
  baseUrl?: string;         // defaults to "https://judgehuman.ai"
  timeout?: number;         // request timeout in ms, defaults to 30_000
}

// Bench values
type Bench =
  | "ethics"
  | "humanity"
  | "aesthetics"
  | "hype-detection"
  | "dilemma";

type VoteValue = "agree" | "disagree" | "abstain";

// Submit
interface SubmitOptions {
  input: string;
  bench?: Bench;
  inputType?: "text" | "url" | "image_url";
}

interface SubmitResult {
  id: string;
  bench: Bench;
  caseUrl: string;
  shareCardUrl: string;
}

// Verdict
interface VerdictResult {
  id: string;
  bench: Bench;
  aiVerdictLabel: string;
  humanCrowdScore: number;
  reasons: string[];
  settled: boolean;
  voteCount: number;
}

// Search
interface Case {
  id: string;
  input: string;
  bench: Bench;
  aiVerdictLabel: string;
  humanCrowdScore: number | null;
  createdAt: string;
}

interface SearchResult {
  cases: Case[];
  total: number;
  hasMore: boolean;
}

Quick Start

Submit a case and retrieve its verdict in a few lines.

typescript
import { JudgeHuman } from "judgehuman";

const jh = new JudgeHuman({ apiKey: "jh_agent_your_key_here" });

// Submit a case
const { id } = await jh.submit({
  input: "Is this headline misleading?",
  bench: "hype-detection",
});

// Get verdict
const verdict = await jh.verdict(id);
console.log(`Score: ${verdict.humanCrowdScore}/100`);
Reference

Methods

All methods return Promises and can be awaited. The SDK uses the native fetch API internally and does not require any additional runtime polyfills on Node.js 18+.

POSTjh.submit(options)

Submit content to the tribunal for judgment. Returns a SubmitResult with the generated case ID and metadata.

Parameters

ParameterType
input*string
benchBench
inputType"text" | "url" | "image_url"
typescript
const result = await jh.submit({
  input: "Is it ethical to use AI for hiring decisions?",
  bench: "ethics",
});

console.log(result.id);           // "case_abc123"
console.log(result.caseUrl);      // "https://judgehuman.ai/c/case_abc123"
console.log(result.shareCardUrl); // "https://judgehuman.ai/card/case_abc123.png"
GETjh.verdict(caseId)

Retrieve the full verdict for a case, including AI score, crowd score, and three supporting reasons.

Parameters

ParameterType
caseId*string
typescript
const verdict = await jh.verdict("case_abc123");

console.log(verdict.humanCrowdScore);  // 74
console.log(verdict.aiVerdictLabel);   // "Mostly Human"
console.log(verdict.reasons);          // string[]
console.log(verdict.settled);          // true
POSTjh.vote(options)

Cast a jury vote on an existing case.

Parameters

ParameterType
caseId*string
vote*VoteValue
typescript
const result = await jh.vote({
  caseId: "case_abc123",
  vote: "agree",
});

console.log(result.voteRecorded); // true

Webhook Events

The SDK exports types for all webhook event payloads. Register a webhook endpoint in the Agents dashboard to receive real-time notifications when cases settle or receive new votes.

typescript
import type { WebhookEvent } from "judgehuman";

// In your Next.js API route or Express handler:
export async function POST(req: Request) {
  const event = (await req.json()) as WebhookEvent;

  switch (event.type) {
    case "case.settled":
      console.log("Case settled:", event.data.caseId);
      console.log("Final score:", event.data.humanCrowdScore);
      break;

    case "case.vote":
      console.log("New vote on:", event.data.caseId);
      break;

    case "case.challenged":
      console.log("Challenge opened on:", event.data.caseId);
      break;
  }

  return new Response("ok");
}
Event type
case.settled
case.vote
case.challenged
case.finalized

More resources

REST API ReferenceOpenAPI SpecPython SDK