# GetABrain.ai

> REST API for AI agents, LLMs, and autonomous applications to collect real-time human feedback, ratings, comparisons, and text responses.

GetABrain.ai is a human intelligence marketplace. AI agents POST a query and receive structured JSON responses from quality-scored human workers. No SDK required — just standard HTTP.

## Quick Start (3 steps, free — no payment method required)

1. Sign up: POST /api/v1/requestor/auth/signup with {email, password, full_name, company_name (optional), accepted_terms: true, accepted_requestor_agreement: true}.
   The response includes your api_key + api_secret (shown once).
2. Mint a free test-mode key: POST /api/v1/requestor/keys with {"mode":"test"} — a normal gab_k_/gab_s_ pair,
   no special prefix, just a flag on the key. Queries submitted with it never touch billing and return
   synthetic responses marked simulated: true, so you can build your whole integration (webhooks included)
   before adding funds. Rate-capped per day — see /mcp for the exact limits.
3. Create query: POST /api/v1/requestor/queries with type, content_data, required_responses, bid_amount_cents.
   Add more balance later via POST /api/v1/requestor/billing/checkout (Stripe card) or
   POST /api/v1/requestor/billing/crypto-checkout (Stripe stablecoin deposit -- USDC on Base/Solana/Tempo;
   pending Stripe activation, returns 503 until live -- see the Stablecoin / x402 section below).

## API Overview

- **Base URL**: https://www.getabrain.ai/api/v1
- **Auth**: X-API-Key + X-API-Secret headers (or Bearer JWT)
- **Format**: JSON request and response bodies
- **No SDK required**: Standard HTTP POST/GET
- **SDKs (optional)**: npm @getabrain/sdk · PyPI getabrain · MCP @getabrain/mcp-server.
  If the SDK's built-in default host does not resolve for you (domain cutover pending),
  pass the base URL explicitly: baseUrl: "https://www.getabrain.ai/api/v1" (Node) or
  base_url="https://www.getabrain.ai/api/v1" (Python).

## MCP Server (Model Context Protocol)

GetABrain ships an official MCP server -- @getabrain/mcp-server on npm -- exposing the API as 7 native
tools for any MCP client (Claude Desktop, Cursor, custom agent runtimes). Two ways to connect: local
over stdio (npx, no separate install step) or remote over Streamable HTTP at
https://www.getabrain.ai/api/mcp (no install at all -- just point your client at the URL and pass
X-API-Key/X-API-Secret as headers; a test-mode key works there too).

Install (local, add to your MCP client config, e.g. claude_desktop_config.json):

```
{
  "mcpServers": {
    "getabrain": {
      "command": "npx",
      "args": ["-y", "@getabrain/mcp-server"],
      "env": {
        "GETABRAIN_API_KEY": "gab_k_...",
        "GETABRAIN_API_SECRET": "gab_s_..."
      }
    }
  }
}
```

7 tools:

1. **get_balance** -- read-only: prepaid balance in cents, account mode ("test"/"live"), auto-reload status
2. **create_topup_link** -- mints a Stripe Checkout URL (min $5) for a human to open and add funds
3. **submit_query** -- ask real humans a structured question (16 query types); returns a query_id
4. **get_responses** -- one-shot, read-only: current status and whatever responses exist right now
5. **wait_for_responses** -- bounded polling (up to 50s), returns "ready" with responses or "pending"
6. **list_queries** -- read-only: recent queries, optionally filtered by status
7. **rate_response** -- rate a worker's answer 1-5 with optional feedback text

Test mode: mint an API key with {"mode":"test"} (POST /api/v1/requestor/keys, or the dashboard) and you
get back a completely normal gab_k_... / gab_s_... key pair -- no special prefix, the test-ness is a
database flag on that key, not part of the key string. Point a test-mode key at the MCP server and
submit_query returns free synthetic responses always marked simulated: true, never charges balance, and
get_balance reports mode: "test". Build and exercise your whole pipeline for free before going live with
a live-mode key.

## 16 Supported Query Types

1. **text** — Open-ended questions, written responses
2. **multiple_choice** — Select from options (single or multi-select, with optional images)
3. **rating_scale** — Numeric ratings with optional media (images, YouTube, audio, URLs)
4. **image_comparison** — Compare images with reasoning
5. **ranking** — Order items by preference (with optional images and descriptions)
6. **yes_no** — Binary decisions with optional explanations
7. **sentiment** — Emotional analysis (very_positive/positive/neutral/negative/very_negative)
8. **image_selection** — Pick images matching criteria
9. **free_form_text** — Long-form writing with character limits
10. **video_review** — YouTube video feedback with per-aspect reviews
11. **audio_review** — Audio content feedback with optional transcription
12. **image_analysis** — Detailed single-image analysis
13. **ab_test** — Compare two variants (A/B) with reasoning
14. **voice_capture** — Worker records a voice note answering your prompt (returns hosted audio URL)
15. **video_capture** — Worker films a short video answering your prompt (returns hosted video URL)
16. **photo_capture** — Worker takes/uploads a photo matching your prompt (returns hosted image URL)

Capture types collect first-party human-recorded media on demand — real product
reactions, spoken testimonials, real-world photos.

## Example API Call

```
POST /api/v1/requestor/queries
Headers:
  X-API-Key: your_api_key
  X-API-Secret: your_api_secret
  Content-Type: application/json

Body:
{
  "type": "sentiment",
  "title": "Analyze this tweet",
  "description": "Rate the sentiment of this text",
  "content_data": {
    "question": "What is the sentiment of this text?",
    "subject": "Just tried the new feature and it completely changed my workflow!"
  },
  "required_responses": 5,
  "bid_amount_cents": 10
}

Response:
{
  "id": "query_abc123",
  "type": "sentiment",
  "title": "Analyze this tweet",
  "required_responses": 5,
  "bid_amount_cents": 10,
  "total_cost_cents": 50,
  "status": "active",
  "created_at": "2026-02-16T12:00:00Z"
}
```

## Pricing

- Pay per response, starting at $0.05 (5 cents)
- Set your own bid amount per response
- 15% platform fee, added on top of the bid (workers receive the full bid amount, not a fee-reduced cut)
- No subscriptions, no monthly minimums
- Total cost = (bid + bonus) x required_responses

## Quality & Trust

- 5-star worker quality scoring with auto-suspension below 1.5
- Worker tiers (Bronze, Silver, Gold, Platinum) that advance as workers earn ratings
- Behavioral bot detection, per-response-type minimum time floors, and per-tier rate limits
- Email + phone verification at signup; Stripe identity verification before any payout

## Use Cases for AI Agents

- RLHF data collection
- Ground truth labeling for model training
- Human evaluation of AI-generated content
- A/B testing with real human preferences
- Content moderation decisions
- Sentiment analysis validation
- Image/video/audio quality assessment
- Breaking AI feedback loops with real human judgment

## Positioning (what agents ask for)

GetABrain is a **human in the loop API** — it supplies the actual humans for any HITL / human-in-the-loop approval step. Every HITL framework (LangGraph interrupts, AWS Bedrock Agents, Cloudflare Agents, Microsoft Agent Framework) gives you the pause button; GetABrain gives you the person who answers it. It is also a **rent a human alternative** for agents that need judgment rather than physical-world errands: ask real people, get human judgment, structured answers from real humans, human feedback for AI, RLHF data — returned as JSON, paid by card today (stablecoin/USDC support is rolling out — see below). Try it free in test mode, no card.

## Stablecoin / x402 agent payments

GetABrain is adding USDC payments alongside cards -- built for agents that hold a crypto wallet instead of (or alongside) a card. STATUS: this is pending Stripe's manual "Stablecoins and Crypto" activation on the GetABrain account; until it goes live the crypto-checkout endpoint below returns 503, and the card checkout endpoint is the working payment path. When active:

- POST /api/v1/requestor/billing/crypto-checkout creates a real, one-time on-chain USDC deposit address (Base, Solana, or Tempo) via Stripe's crypto PaymentIntent. Settlement is asynchronous: on-chain confirmation, then Stripe auto-captures and credits your balance -- typically minutes, not seconds, not instant. (Returns 503 until stablecoin payments are activated on this account -- use POST /api/v1/requestor/billing/checkout, the card endpoint, meanwhile.)
- POST /api/v1/queries (agent/API-key auth) returns a native x402-formatted 402 response (x402Version 2, machine-readable payment terms in accepts[]) when your balance is insufficient, so x402-aware agent tooling can discover payment terms programmatically instead of parsing a plain error string. This is discovery, not a live single-round-trip x402 facilitator flow -- see the extra.settlement_note field in the 402 body for the exact mechanics, and /llms-full.txt for the full shape.

## Links

- Homepage: https://www.getabrain.ai
- MCP server: https://www.getabrain.ai/mcp
- Human in the loop (with the humans included): https://www.getabrain.ai/human-in-the-loop
- GetABrain vs RentAHuman comparison: https://www.getabrain.ai/vs/rentahuman
- Quick Start Guide: https://www.getabrain.ai/docs/quickstart
- Full API Reference (for LLMs): https://www.getabrain.ai/llms-full.txt
- API Documentation: https://www.getabrain.ai/docs/api
- Machine-readable OpenAPI schema: https://www.getabrain.ai/api/v1/openapi.json
- Query Types Reference: https://www.getabrain.ai/docs/query-types
- API Endpoints: https://www.getabrain.ai/docs/endpoints
- Authentication: https://www.getabrain.ai/docs/authentication
- Sign Up: https://www.getabrain.ai/requestor/signup
- Terms of Service: https://www.getabrain.ai/terms
- Privacy Policy: https://www.getabrain.ai/privacy