Quick Start Guide

Sign up at /requestor/signup or call the signup API directly:

curl -X POST https://getabrain.ai/api/v1/requestor/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "password": "SecurePass123",
    "full_name": "Jane Smith",
    "company_name": "Acme AI",
    "accepted_terms": true,
    "accepted_requestor_agreement": true
  }'

You get back your credentials:

{
  "user": { "id": "abc123", "email": "you@company.com", "balance_cents": 0 },
  "api_key": "gab_k_xxxxx",
  "api_secret": "gab_s_xxxxx",
  "access_token": "eyJhbG...",
  "refresh_token": "eyJhbG..."
}

Queries require a prepaid balance. Create a Stripe checkout session to add funds:

curl -X POST https://getabrain.ai/api/v1/requestor/billing/checkout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 5000 }'

This returns a checkout_url. Open it in a browser to complete payment via Stripe. After payment, your balance is credited automatically.

How billing works:

• Prepaid balance model — no subscriptions or monthly fees
• Minimum bid per response: $0.05 (5 cents)
• Platform fee: 15% (included in cost, not added on top)
• Total cost = (bid + bonus) × required_responses
• Balance is deducted when you create a query, refunded if you cancel
• Optional auto-reload: set a threshold and reload amount to never run out

POST a query to get real human responses. Choose from 13 query types. Here is the simplest example — a text question:

cURL

curl -X POST https://getabrain.ai/api/v1/requestor/queries \
  -H "X-API-Key: gab_k_xxxxx" \
  -H "X-API-Secret: gab_s_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "title": "Landing page feedback",
    "description": "We need honest feedback on our new design",
    "content_data": {
      "question": "What is your first impression of this landing page?",
      "context": "We just redesigned our homepage."
    },
    "required_responses": 5,
    "bid_amount_cents": 50
  }'

Python

import requests

resp = requests.post(
    "https://getabrain.ai/api/v1/requestor/queries",
    headers={
        "X-API-Key": "gab_k_xxxxx",
        "X-API-Secret": "gab_s_xxxxx",
    },
    json={
        "type": "text",
        "title": "Landing page feedback",
        "description": "We need honest feedback on our new design",
        "content_data": {
            "question": "What is your first impression of this landing page?",
        },
        "required_responses": 5,
        "bid_amount_cents": 50,
    },
)
query = resp.json()
print(f"Query ID: {query['id']}, Status: {query['status']}")

Node.js

const resp = await fetch("https://getabrain.ai/api/v1/requestor/queries", {
  method: "POST",
  headers: {
    "X-API-Key": "gab_k_xxxxx",
    "X-API-Secret": "gab_s_xxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "text",
    title: "Landing page feedback",
    description: "We need honest feedback on our new design",
    content_data: {
      question: "What is your first impression of this landing page?",
    },
    required_responses: 5,
    bid_amount_cents: 50,
  }),
});
const query = await resp.json();
console.log("Query ID:", query.id, "Status:", query.status);

Response:

{
  "id": "query_abc123",
  "type": "text",
  "status": "active",
  "required_responses": 5,
  "completed_responses": 0,
  "total_cost_cents": 250,
  "created_at": "2026-02-16T12:00:00Z"
}

Poll your query to check for responses, or use webhooks for real-time notifications.

Polling

curl https://getabrain.ai/api/v1/requestor/queries/query_abc123 \
  -H "X-API-Key: gab_k_xxxxx" \
  -H "X-API-Secret: gab_s_xxxxx"

{
  "id": "query_abc123",
  "status": "completed",
  "completed_responses": 5,
  "responses": [
    {
      "id": "resp_001",
      "response_data": {
        "answer": "The hero section is eye-catching. The CTA button could be more prominent.",
        "reasoning": "I looked at the overall visual hierarchy."
      },
      "worker": { "quality_score": 4.2, "tier": "Gold" },
      "submitted_at": "2026-02-16T12:05:00Z"
    },
    ...
  ]
}

Webhooks (recommended for production)

Include a webhook_url in your query creation request. We POST a JSON payload to your URL when each response arrives and when the query completes. See the Webhooks guide for details.

Rate each response 1–5 stars to improve the quality of future workers assigned to your queries. Workers with consistently low ratings are automatically suspended.

curl -X POST https://getabrain.ai/api/v1/requestor/queries/query_abc123/responses/resp_001/rate \
  -H "X-API-Key: gab_k_xxxxx" \
  -H "X-API-Secret: gab_s_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "score": 5, "feedback_text": "Excellent, detailed feedback." }'