# GetABrain.ai — API Reference for AI Agents & LLMs
#
# Real human judgment as an API. Submit a query, receive structured JSON answers from quality-scored human workers.
# Base URL: https://www.getabrain.ai/api/v1
# Full machine-readable schema: https://www.getabrain.ai/api/v1/openapi.json
# Interactive docs: https://www.getabrain.ai/docs/api

================================================================================
AUTHENTICATION
================================================================================
Server-to-server (recommended): send your API key pair as headers
  X-API-Key: gab_k_...
  X-API-Secret: gab_s_...
Or a session JWT: Authorization: Bearer <access_token>  (from POST /requestor/auth/login)

================================================================================
ENDPOINTS
================================================================================
POST https://www.getabrain.ai/api/v1/requestor/auth/signup  — Register a new requestor.
  Body: {email, password, full_name, company_name, accepted_terms: true, accepted_requestor_agreement: true}
  Returns api_key + api_secret (shown once) and a $5.00 free trial credit
  (trial_credit.status = "pending_email_verification"). Verify the email to make it spendable.
GET https://www.getabrain.ai/api/v1/requestor/auth/verify-email?token=...  — Verify email (from the emailed link); activates the trial credit
POST https://www.getabrain.ai/api/v1/requestor/auth/resend-verification  — Resend the verification link. Body: {email}
POST https://www.getabrain.ai/api/v1/requestor/auth/login  — Log in
GET https://www.getabrain.ai/api/v1/requestor/keys  — List API keys
POST https://www.getabrain.ai/api/v1/requestor/keys  — Create an API key (secret shown once)
DELETE https://www.getabrain.ai/api/v1/requestor/keys/{id}  — Revoke an API key
POST https://www.getabrain.ai/api/v1/requestor/queries  — Create a query
GET https://www.getabrain.ai/api/v1/requestor/queries  — List queries
GET https://www.getabrain.ai/api/v1/requestor/queries/{id}  — Get a query with its responses
PUT https://www.getabrain.ai/api/v1/requestor/queries/{id}  — Cancel a query
POST https://www.getabrain.ai/api/v1/requestor/queries/{id}/responses/{responseId}/rate  — Rate a response
GET https://www.getabrain.ai/api/v1/requestor/queries/{id}/responses/{responseId}/rate  — Get a response rating
GET https://www.getabrain.ai/api/v1/requestor/stats  — Account stats
GET https://www.getabrain.ai/api/v1/requestor/billing  — Balance and transactions
POST https://www.getabrain.ai/api/v1/requestor/billing/checkout  — Create a Stripe Checkout session to add balance
GET https://www.getabrain.ai/api/v1/requestor/webhook  — Current webhook config
PUT https://www.getabrain.ai/api/v1/requestor/webhook  — Set webhook URL. Body: {webhook_url}. Returns the HMAC signing secret ONCE.
DELETE https://www.getabrain.ai/api/v1/requestor/webhook  — Disable webhooks
  Events: response.submitted, query.completed — signed JSON POSTs (X-GAB-Signature =
  HMAC-SHA256 hex of raw body keyed with your webhook secret; also X-GAB-Event,
  X-GAB-Timestamp). 10s timeout, ~5 retries a minute apart. Per-query override:
  pass webhook_url when creating a query. https URLs only.

================================================================================
QUERY TYPES — content_data and response_data fields
(set "type" + "content_data" on POST /requestor/queries)
================================================================================

### text
content_data:
  question (string, required)
  instructions (string)
  context (string)
  min_words (integer)
  max_words (integer)
  required_fields (array<string>)
response_data:
  answer (string, required)
  reasoning (string)

### multiple_choice
content_data:
  question (string, required)
  instructions (string)
  context (string)
  options (array<object>, required)
  allow_multiple (boolean)
  min_selections (integer)
  max_selections (integer)
response_data:
  selected_ids (array<string>, required)
  reasoning (string)

### rating_scale
content_data:
  question (string, required)
  instructions (string)
  context (string)
  scale_type (enum(1-5|1-10|0-100|stars), required)
  scale_min (number, required)
  scale_max (number, required)
  scale_labels (object)
  criteria (array<string>)
response_data:
  rating (number, required)
  criteria_ratings (object)
  feedback (string)

### image_comparison
content_data:
  question (string, required)
  instructions (string)
  context (string)
  images (array<object>, required)
  comparison_type (enum(preference|quality|relevance|custom), required)
  require_reasoning (boolean)
response_data:
  selected_image_id (string, required)
  ranking (array<string>)
  reasoning (string, required)

### ranking
content_data:
  question (string, required)
  instructions (string)
  context (string)
  items (array<object>, required)
  max_items (integer, required)
  require_all (boolean)
response_data:
  ranked_ids (array<string>, required)
  reasoning (string)

### yes_no
content_data:
  question (string, required)
  instructions (string)
  context (string)
  require_explanation (boolean)
  min_explanation_words (integer)
response_data:
  answer (enum(yes|no), required)
  explanation (string)

### sentiment
content_data:
  question (string, required)
  instructions (string)
  context (string)
  subject (string, required)
  sentiment_options (array<string>, required)
  require_reasoning (boolean)
response_data:
  sentiment (enum(very_positive|positive|neutral|negative|very_negative), required)
  reasoning (string)
  confidence_level (number)

### image_selection
content_data:
  question (string, required)
  instructions (string)
  context (string)
  images (array<object>, required)
  min_selections (integer, required)
  max_selections (integer, required)
  selection_criteria (string, required)
response_data:
  selected_image_ids (array<string>, required)
  reasoning (string)

### free_form_text
content_data:
  question (string, required)
  instructions (string)
  context (string)
  prompt (string, required)
  min_characters (integer)
  max_characters (integer)
  format_guidelines (string)
response_data:
  text (string, required)
  word_count (integer, required)

### video_review
content_data:
  question (string, required)
  instructions (string)
  context (string)
  video_url (string, required)
  video_duration_seconds (integer, required)
  review_aspects (array<string>, required)
  min_watch_time_seconds (integer)
response_data:
  watched_seconds (integer, required)
  review (object, required)
  overall_feedback (string, required)
  rating (number)

### audio_review
content_data:
  question (string, required)
  instructions (string)
  context (string)
  audio_url (string, required)
  audio_duration_seconds (integer, required)
  review_aspects (array<string>, required)
  transcription_required (boolean)
response_data:
  listened_seconds (integer, required)
  review (object, required)
  overall_feedback (string, required)
  transcription (string)

### image_analysis
content_data:
  question (string, required)
  image_url (string, required)
response_data:
  analysis (string)
  observations (string)

### ab_test
content_data:
  question (string, required)
  variant_a (object, required)
  variant_b (object, required)
response_data:
  choice (enum(A|B), required)
  reasoning (string)

### voice_capture  (worker records a voice note in response to your prompt)
content_data:
  prompt (string, required)
  max_duration_seconds (integer)
response_data:
  audio_url (string, required — hosted URL the worker uploaded via POST /workers/uploads)
  duration_seconds (integer)
  transcription (string)

### video_capture  (worker films a short video in response to your prompt)
content_data:
  prompt (string, required)
  max_duration_seconds (integer)
response_data:
  video_url (string, required — hosted URL the worker uploaded via POST /workers/uploads)
  duration_seconds (integer)

### photo_capture  (worker takes or uploads a photo matching your prompt)
content_data:
  prompt (string, required)
response_data:
  image_url (string, required — hosted URL the worker uploaded via POST /workers/uploads)
  caption (string)

================================================================================
ERROR CODES (envelope: { "error": string, "message": string })
================================================================================
200 OK · 201 Created · 400 Validation · 401 Unauthorized · 402 Insufficient balance
403 Forbidden · 404 Not found · 409 Conflict · 429 Rate limited · 500 Server error · 503 Service unavailable