@getabrain/sdk

Official Node/TypeScript SDK for GetABrain.ai — real human judgment as an API.

Install

npm install @getabrain/sdk

Quickstart

import { GetABrain } from '@getabrain/sdk'

const gab = new GetABrain({ apiKey: 'gab_k_…', apiSecret: 'gab_s_…' })

// Submit a question (returns immediately)
const query = await gab.queries.create({
  type: 'ab_test',
  title: 'Which headline converts better?',
  content_data: {
    question: 'Which is more compelling?',
    variant_a: { description: 'Save 20% today' },
    variant_b: { description: 'Your future self will thank you' },
  },
  required_responses: 5,
  bid_amount_cents: 25,
})

// Wait for humans to answer (polls for you)
const responses = await gab.queries.waitForResponses(query.id, { minResponses: 5 })
console.log(responses.map((r) => r.response_data))

Test mode

Sign up at https://getabrain.ai and mint a free test key pair (no funding required) to build against the full API without spending anything: gab.queries.create(...) succeeds with no balance check, and responses come back synthetic with simulated: true on each one. gab.account.balance() reports mode: 'test' so you can confirm which environment you're authenticated against. Swap in a live key pair (and top up via the create_topup_link endpoint / the MCP server's create_topup_link tool) when you're ready for real human workers and real spend.

Errors

import { InsufficientBalanceError, RateLimitError } from '@getabrain/sdk'

try {
  await gab.queries.create(/* … */)
} catch (e) {
  if (e instanceof InsufficientBalanceError) {
    // top up your balance at https://getabrain.ai
  }
}

Stablecoin / x402 payments

Balance top-ups also accept USDC (Base/Solana/Tempo), not just cards, via a Stripe crypto PaymentIntent -- settlement is asynchronous (on-chain confirmation + Stripe capture, not instant). The SDK doesn't wrap the billing endpoints yet (gab.account.balance() is read-only), so call the REST endpoints directly with your API key pair:

// Mint a real, one-time on-chain USDC deposit address for $50
const res = await fetch('https://www.getabrain.ai/api/v1/requestor/billing/crypto-checkout', {
  method: 'POST',
  headers: { 'X-API-Key': apiKey, 'X-API-Secret': apiSecret, 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount_cents: 5000, network: 'base' }),
})
const { deposit_details } = await res.json() // send USDC here, then poll gab.account.balance()

When InsufficientBalanceError is thrown, err.paymentRequired carries the raw x402 v2 payment-terms body on 402 responses that include one -- e.g. err.paymentRequired?.accepts?.[0]?.extra?.deposit_endpoint -- for x402-aware agent tooling that wants to discover payment terms programmatically instead of just catching the error. As of this writing, gab.queries.create(...) calls POST /requestor/queries, whose 402 is the plain {error, message} shape (paymentRequired will be undefined); the x402-formatted body is currently only returned by the bare POST /api/v1/queries route. This SDK doesn't call that route directly, but the parsing is defensive/forward-compatible in case that changes.

API

• gab.queries.create(input) / .get(id) / .list({ status?, limit?, offset? }) / .cancel(id)
• gab.queries.waitForResponses(id, { minResponses, timeoutMs?, pollIntervalMs? })
• gab.responses.rate(queryId, responseId, { score, feedback_text? }) / .getRating(queryId, responseId)
• gab.account.stats() / .balance()

Full reference: https://getabrain.ai/docs/api

The SDK types all 16 live query types. Two legacy types (custom, headline_test) exist server-side but are intentionally undocumented and not typed by the SDK — use a first-class type instead.