API Endpoints

Complete reference for all GetABrain.ai REST API endpoints. All endpoints require authentication. The base URL is https://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

Example Request

curl -X POST https://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)

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

GET /api/v1/queries

List all queries for the authenticated requestor. Supports pagination.

Query Parameters

Example Request

curl "https://getabrain.ai/api/v1/queries?page=1&limit=10&status=open" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response (200 OK)

{
  "queries": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "text",
      "title": "Product Feedback",
      "status": "open",
      "required_responses": 3,
      "received_responses": 1,
      "bid_amount_cents": 50,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "total_pages": 1
  }
}

GET /api/v1/queries/:id

Get a single query by ID, including its responses.

Example Request

curl https://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)

{
  "query": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "text",
    "title": "Product Feedback",
    "status": "completed",
    "content_data": {
      "question": "What improvements would you suggest?"
    },
    "required_responses": 3,
    "received_responses": 3,
    "bid_amount_cents": 50,
    "created_at": "2025-01-15T10:30:00Z",
    "completed_at": "2025-01-15T10:45:00Z"
  },
  "responses": [
    {
      "id": "resp-001",
      "response_data": { "answer": "Better onboarding flow." },
      "quality_score": 0.91,
      "submitted_at": "2025-01-15T10:35:00Z"
    },
    {
      "id": "resp-002",
      "response_data": { "answer": "Add more integrations." },
      "quality_score": 0.87,
      "submitted_at": "2025-01-15T10:38:00Z"
    },
    {
      "id": "resp-003",
      "response_data": { "answer": "Improve the search feature." },
      "quality_score": 0.94,
      "submitted_at": "2025-01-15T10:42: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

Example Request

curl -X PUT https://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)

{
  "query": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "cancelled",
    "refunded_cents": 100
  },
  "message": "Query cancelled. $1.00 refunded to your balance."
}

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

Get all responses for a specific query.

Example Request

curl https://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)

{
  "responses": [
    {
      "id": "resp-001",
      "worker_id": "worker-uuid",
      "response_data": { "answer": "Better onboarding flow." },
      "quality_score": 0.91,
      "submitted_at": "2025-01-15T10:35:00Z"
    }
  ],
  "total": 1
}

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

Example Request

curl -X POST https://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 '{
    "rating": 5,
    "feedback": "Excellent, detailed response."
  }'

Response (200 OK)

{
  "message": "Response rated successfully.",
  "rating": 5
}

Status Codes

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

Error Response Format

All error responses follow a consistent JSON format:

{
  "error": "Validation failed",
  "details": [
    "bid_amount_cents must be at least 5",
    "required_responses must be between 1 and 100"
  ]
}