Most APIs an agent calls return facts: today's weather, a stock price, a search result. This one returns an opinion — a real person's judgment on something only a person can judge. If your agent needs to know whether a joke actually lands, whether a photo looks staged, or whether a reply sounds too robotic, that's not a lookup, it's a question for a human. GetABrain is the API for asking it.
What "ask a human" means as an API call
Structurally it looks like any other REST call: POST a JSON body with X-API-Key and X-API-Secret headers, get a JSON response back. The difference is what happens between the request and the response — instead of a database lookup or a model inference, a real person on GetABrain's worker marketplace reads your question and answers it.
You pick a query type (16 available — yes/no, rating scale, multiple choice, sentiment, ranking, A/B comparison, free text, and more), set how many people should answer (required_responses), and set what you're paying per response (bid_amount_cents, starting at $0.05). POST to /api/v1/requestor/queries and you get back a query_id to poll or a webhook to wait on.
Why an agent would ever need this
LLMs are good at generating plausible answers and bad at knowing when their own output is actually right for a subjective goal. "Is this ad copy funny", "does this UI screenshot look broken to a real user", "would a human find this email pushy" — none of these have a ground truth an agent can check against itself. Asking a model to grade its own subjective output just gets you another guess dressed up as a verdict.
The pattern that works: the agent does the generation, GetABrain supplies the judgment, and the agent uses that judgment to pick a winner, gate a send, or flag something for review — all without a person on your team having to be online watching a queue.
The request/response contract
Auth: X-API-Key + X-API-Secret headers (Bearer JWT also works). Sign up with POST /api/v1/requestor/auth/signup — email, password, name, accept the terms — and the response hands you both keys once. No waitlist, no sales call.
Then mint a free test-mode key: POST /api/v1/requestor/keys with {"mode": "test"}. It's a completely normal key pair — same gab_k_/gab_s_ shape — just flagged in the database so queries submitted with it never touch billing and come back with synthetic answers marked simulated: true. Build and test the entire integration, webhooks included, before a card ever enters the picture.
Real answers come back as typed JSON matching the query type you sent — a 1-5 number for rating_scale, a label for sentiment, structured reasoning for ab_test — never a paragraph of prose you have to parse yourself.
MCP-native for agent runtimes that already speak MCP
If your agent runtime supports Model Context Protocol (Claude Desktop, Cursor, or a custom runtime), GetABrain ships an official server — @getabrain/mcp-server — with 7 tools: submit_query, wait_for_responses (bounded polling up to 50s), get_responses, list_queries, rate_response, get_balance, and create_topup_link. Asking a human becomes a tool call sitting next to your other tools, no REST plumbing required. It's also reachable over remote Streamable HTTP at https://getabrain.ai/api/mcp with zero local install.
import requests
# Agent drafted an outbound message; get a human yes/no before it sends.
resp = requests.post(
"https://www.getabrain.ai/api/v1/requestor/queries",
headers={"X-API-Key": API_KEY, "X-API-Secret": API_SECRET},
json={
"type": "yes_no",
"title": "Does this message sound too pushy?",
"content_data": {
"question": "Would you say this email sounds pushy or salesy?",
"subject": draft_message,
},
"required_responses": 3,
"bid_amount_cents": 10,
},
).json()
query_id = resp["id"]
# Poll GET /api/v1/requestor/queries/{query_id} (or wait_for_responses over MCP)
# until 3 humans have answered, then gate the send on majority vote.
# Use a {"mode": "test"} key first: identical request/response shape, free
# simulated answers, nothing billed — verify the gate logic before going live.