GetABrain.ai

API Endpoints

Complete reference for all GetABrain.ai REST API endpoints. All endpoints require authentication. The base URL is https://www.getabrain.ai/api/v1.

POST /api/v1/queries

Create a new query. The bid amount is held in escrow from your account balance. Workers will be matched and begin responding once the query is created.

Request Body

FieldTypeRequiredDescription
typestringYesOne of the 16 query types
titlestringYesShort descriptive title for the query
content_dataobjectYesQuery-type-specific data (see query types)
required_responsesintegerYesNumber of worker responses needed (1-1000)
bid_amount_centsintegerYesPayment per response in cents (min 5)
bonus_amount_centsintegerNoOptional bonus for high-quality responses
webhook_urlstringNoPublic https URL to receive signed webhook events for this query

Example Request

curl -X POST https://www.getabrain.ai/api/v1/queries \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "type": "text",
    "title": "Product Feedback",
    "content_data": {
      "question": "What improvements would you suggest?"
    },
    "required_responses": 3,
    "bid_amount_cents": 50
  }'

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "text",
  "title": "Product Feedback",
  "description": null,
  "required_responses": 3,
  "bid_amount_cents": 50,
  "bonus_amount_cents": 0,
  "total_cost_cents": 150,
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z",
  "expires_at": null
}

GET /api/v1/queries

List all queries for the authenticated requestor. Supports pagination.

Query Parameters

ParamTypeDefaultDescription
offsetinteger0Number of results to skip
limitinteger20Results per page (max 100)
statusstringallFilter by status: pending, active, completed, cancelled, failed, expired
typestringallFilter by query type

Example Request

curl "https://www.getabrain.ai/api/v1/queries?limit=10&offset=0&status=active" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response (200 OK)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "text",
      "title": "Product Feedback",
      "status": "active",
      "required_responses": 3,
      "completed_responses": 1,
      "bid_amount_cents": 50,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0,
  "has_more": false
}

GET /api/v1/queries/:id

Get a single query by ID. This returns the query record only -- use GET /api/v1/queries/:id/responses (below) to fetch its responses.

Example Request

curl https://www.getabrain.ai/api/v1/queries/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "text",
  "title": "Product Feedback",
  "status": "completed",
  "content_data": {
    "question": "What improvements would you suggest?"
  },
  "required_responses": 3,
  "completed_responses": 3,
  "bid_amount_cents": 50,
  "total_cost_cents": 150,
  "created_at": "2025-01-15T10:30:00Z"
}

PUT /api/v1/queries/:id

Update a query. Currently supports cancelling an open query. The escrowed funds for unfulfilled responses are returned to your balance.

Request Body

FieldTypeDescription
actionstring"cancel" -- cancels the query

Example Request

curl -X PUT https://www.getabrain.ai/api/v1/queries/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{ "action": "cancel" }'

Response (200 OK)

{
  "success": true,
  "message": "Query cancelled",
  "refund_amount_cents": 100
}

GET /api/v1/queries/:id/responses

Get all responses for a specific query.

Example Request

curl https://www.getabrain.ai/api/v1/queries/550e8400-e29b-41d4-a716-446655440000/responses \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response (200 OK)

{
  "query_id": "550e8400-e29b-41d4-a716-446655440000",
  "responses": [
    {
      "id": "resp-001",
      "user_id": "worker-uuid",
      "response_data": { "answer": "Better onboarding flow." },
      "quality_score": 0.91,
      "status": "approved",
      "earnings_cents": 50,
      "submitted_at": "2025-01-15T10:35:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "has_more": false
}

POST /api/v1/requestor/queries/:id/responses/:responseId/rate

Rate a worker's response. This helps improve worker matching and quality over time.

Request Body

FieldTypeDescription
scoreintegerRating from 1 to 5
feedback_textstringOptional feedback text (max 1000 chars)

Example Request

curl -X POST https://www.getabrain.ai/api/v1/requestor/queries/QUERY_ID/responses/RESPONSE_ID/rate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "score": 5,
    "feedback_text": "Excellent, detailed response."
  }'

Response (201 Created)

{
  "response_id": "RESPONSE_ID",
  "score": 5,
  "feedback_text": "Excellent, detailed response.",
  "worker_new_quality_score": 4.6,
  "worker_new_rating_count": 12,
  "worker_suspended": false,
  "reward_credited_cents": 5,
  "total_reward_cents": 5
}

Status Codes

The API uses standard HTTP status codes to indicate the outcome of requests.

CodeStatusDescription
200OKRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid request body or parameters
401UnauthorizedMissing or invalid authentication credentials
403ForbiddenAuthenticated but not authorized for this resource
404Not FoundResource does not exist
409ConflictResource conflict (e.g., duplicate idempotency key)
429Too Many RequestsRate limit exceeded. Retry after the specified time
500Internal Server ErrorUnexpected server error

Error Response Format

All error responses follow a consistent JSON format:

{
  "error": "Validation Error",
  "message": "bid_amount_cents: Minimum bid is $0.05"
}