Documentation

Quickstart

Post your first task and pull the worker's response as typed JSON.

1. Request early access — we're in closed beta and onboarding one cohort at a time
2. Generate an API key from the API Keys page
3. POST a task, then poll /v1/tasks/{id} or subscribe to a webhook for the result

npm install @crowdsourcerer/sdk

pip install crowdsourcerer-sdk

curl -X POST https://crowdsourcerer.rebaselabs.online/v1/tasks \
  -H "Authorization: Bearer csk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "label_text",
    "input": {
      "text": "The new iPhone is great!",
      "categories": ["positive", "negative", "neutral"],
      "question": "What is the sentiment?"
    },
    "assignments_required": 3
  }'

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer csk_YOUR_API_KEY

Two token types are accepted:

• API Keys (csk_...) — recommended for production. Create in the dashboard.
• JWT tokens — returned from POST /v1/auth/login. Use for short-lived user sessions.

Task lifecycle

Human tasks go through the worker marketplace. Once posted, the task is visible to skill-matched workers who can claim it, do the work, and submit a typed response within the timeout you set.

Submit a task → get a task_id → poll GET /v1/tasks/{task_id} or subscribe to a webhook. Credits are reserved on submission (worker_reward × assignments plus platform fee) and released to the worker(s) on approval. Unused slots are refunded if the task closes early or no worker claims it before claim_timeout_minutes.

Submit a task

POST /v1/tasks
{
  "type": "label_text",
  "input": {
    "text": "The new iPhone is great!",
    "categories": ["positive", "negative", "neutral"],
    "question": "What is the sentiment?"
  },
  "assignments_required": 3,           // 1–20 workers
  "consensus_strategy": "majority_vote", // any_first | majority_vote | unanimous | requester_review
  "claim_timeout_minutes": 60,         // how long a worker has to submit
  "priority": "normal",                // low | normal | high | urgent
  "webhook_url": "https://..."         // optional
}

Poll for result

GET /v1/tasks/{task_id}

// Response when completed:
{
  "id": "uuid",
  "type": "label_text",
  "status": "completed",
  "execution_mode": "human",
  "output": {
    "summary": "positive (3/3 workers agree)",
    "raw": { "submissions": [...] }
  },
  "credits_used": 9,
  "assignments_required": 3,
  "assignments_completed": 3,
  "created_at": "2026-04-11T00:00:00Z",
  "completed_at": "2026-04-11T00:12:31Z"
}

TypeScript SDK

npm install @crowdsourcerer/sdk

import { CrowdSorcerer } from "@crowdsourcerer/sdk";

const crowd = new CrowdSorcerer({ apiKey: process.env.CROWDSOURCERER_API_KEY! });

// Submit + poll until the worker finishes (or timeout)
const task = await crowd.runTask({
  type: "label_text",
  input: {
    text: "The new iPhone is great!",
    categories: ["positive", "negative", "neutral"],
    question: "What is the sentiment?",
  },
  assignments_required: 3,        // get 3 independent workers
});
console.log(task.output?.summary); // → "positive (3/3 workers agree)"

// Or submit async and poll manually
const { task_id } = await crowd.submitTask({
  type: "moderate_content",
  input: { content: "User-submitted post goes here", guidelines: "..." },
});
const result = await crowd.getTask(task_id);

// Credits
const balance = await crowd.getCredits();
console.log(balance.available); // → 87

Python SDK

pip install crowdsourcerer-sdk

Requires Python 3.9+. Supports both sync and async clients.

Sync client

from crowdsourcerer import CrowdSorcerer

client = CrowdSorcerer(api_key="csk_YOUR_KEY")

# Submit a human task and wait for the worker(s) to finish
task = client.tasks.create("label_text", {
    "text": "The new iPhone is great!",
    "categories": ["positive", "negative", "neutral"],
    "question": "What is the sentiment?",
}, assignments_required=3)

completed = client.tasks.wait(task.id)
print(completed.output)

# Check credits
balance = client.credits.balance()
print(f"Available: {balance.available} credits")

Async client

import asyncio
from crowdsourcerer import AsyncCrowdSorcerer

async def main():
    async with AsyncCrowdSorcerer(api_key="csk_YOUR_KEY") as client:
        # Fan out a batch of rate_quality tasks concurrently
        tasks = await asyncio.gather(*[
            client.tasks.create("rate_quality", {
                "content": ai_output,
                "criteria": "Rate the factual accuracy 1–5",
            }, assignments_required=2)
            for ai_output in pending_outputs
        ])
        results = await asyncio.gather(*[client.tasks.wait(t.id) for t in tasks])
        for r in results:
            print(r.id, r.status, r.output)

asyncio.run(main())

Error handling

from crowdsourcerer import (
    CrowdSorcerer, AuthError, RateLimitError,
    InsufficientCreditsError, TaskError,
)

client = CrowdSorcerer(api_key="csk_YOUR_KEY")

try:
    task = client.tasks.create("verify_fact", {
        "claim": "The Eiffel Tower is 330 metres tall",
    })
    result = client.tasks.wait(task.id)
except InsufficientCreditsError:
    print("Top up at crowdsourcerer.rebaselabs.online/dashboard/credits")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except TaskError as e:
    print(f"Task failed: {e}")
except AuthError:
    print("Invalid API key")

Webhooks

Get notified when tasks complete instead of polling. Set webhook_url when creating a task, or register a persistent endpoint in the dashboard. Deliveries retry up to 3 times with exponential backoff.

POST https://your-server.com/webhook

{
  "task_id": "3f4a1b2c-...",
  "event": "task.completed"
}

Fetch full details from GET /v1/tasks/{task_id} after receiving the event.

Signature verification

Every webhook delivery is signed with your endpoint's secret using HMAC-SHA256. Always verify signatures to ensure requests came from CrowdSorcerer.

The signature is in the X-Crowdsorcerer-Signature header in the format t=TIMESTAMP,v1=HMAC_HEX. The timestamp is also available separately in X-Crowdsorcerer-Timestamp.

Python

import hmac, hashlib, time

def verify_webhook(payload_bytes: bytes, secret: str, sig_header: str,
                   tolerance: int = 300) -> bool:
    """Verify a CrowdSorcerer webhook signature."""
    # Parse "t=TIMESTAMP,v1=SIGNATURE"
    parts = {}
    for part in sig_header.split(","):
        key, _, value = part.partition("=")
        parts[key.strip()] = value.strip()

    timestamp = parts.get("t")
    signature = parts.get("v1")
    if not timestamp or not signature:
        return False

    # Reject old deliveries (replay protection)
    if abs(time.time() - int(timestamp)) > tolerance:
        return False

    # Reconstruct the signed payload: "{timestamp}.{body}"
    sig_input = f"{timestamp}.".encode() + payload_bytes
    expected = hmac.new(
        secret.encode(), sig_input, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your Flask / FastAPI handler:
# sig = request.headers["X-Crowdsorcerer-Signature"]
# verify_webhook(request.get_data(), YOUR_SECRET, sig)

Node.js / TypeScript

import crypto from "crypto";

function verifyWebhook(
  payloadBytes: Buffer, secret: string,
  sigHeader: string, toleranceSec = 300
): boolean {
  const parts: Record<string, string> = {};
  for (const p of sigHeader.split(",")) {
    const [k, ...v] = p.split("=");
    parts[k.trim()] = v.join("=").trim();
  }
  const ts = parts["t"], sig = parts["v1"];
  if (!ts || !sig) return false;

  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false;

  const sigInput = Buffer.concat([
    Buffer.from(ts + "."),
    payloadBytes,
  ]);
  const expected = crypto
    .createHmac("sha256", secret)
    .update(sigInput)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(sig)
  );
}

// In your Express handler:
// const sig = req.headers["x-crowdsorcerer-signature"];
// verifyWebhook(req.body, YOUR_SECRET, sig);

SDK helpers

Both SDKs include built-in webhook verification so you don't have to implement it yourself:

from crowdsourcerer import verify_webhook

is_valid = verify_webhook(
    payload=request.get_data(),
    secret=YOUR_SECRET,
    signature_header=request.headers[
        "X-Crowdsorcerer-Signature"
    ],
)

import { verifyWebhook } from
  "@crowdsourcerer/sdk";

const valid = verifyWebhook(
  req.body,
  process.env.WEBHOOK_SECRET!,
  req.headers[
    "x-crowdsorcerer-signature"
  ],
);

Pipeline AI primitives

Six in-process primitives that pipelines can chain with human steps. They are not submittable via POST /v1/tasks directly — that endpoint rejects them with a 422 pointing at /v1/pipelines. Documented here so pipeline authors know the input schema for each step type.

Credit costs shown are per step. Credits are charged on pipeline execution and refunded on failure.

{
  "type": "llm_generate",
  "input": {
    "messages": [{"role": "user", "content": "Summarize the pros and cons of microservices in 3 bullet points each."}]
  }
}

{
  "type": "data_transform",
  "input": {
    "data": [{"name": "Alice", "score": "87"}, {"name": "Bob", "score": "92"}],
    "transform": "Sort by score descending and add a rank column",
    "output_format": "json"
  }
}

{
  "type": "web_research",
  "input": {
    "url": "https://news.ycombinator.com",
    "instruction": "List the top 5 story titles"
  }
}

{
  "type": "document_parse",
  "input": {
    "url": "https://example.com/report.pdf"
  }
}

{
  "type": "pii_detect",
  "input": {
    "text": "Call John Smith at john@example.com or 555-123-4567",
    "mask": true
  }
}

{
  "type": "code_execute",
  "input": {
    "code": "import json\ndata = [1, 2, 3, 4, 5]\nprint(json.dumps({'sum': sum(data), 'mean': sum(data)/len(data)}))",
    "language": "python"
  }
}

Human task types

8 task types completed by human workers. Best for subjective judgments, quality evaluation, and tasks requiring human context.

Credit costs are the base worker reward per assignment. Total cost = (worker_reward × assignments) + platform_fee where platform fee is 20% (minimum 1 credit).

{
  "type": "label_image",
  "input": {
    "image_url": "https://example.com/photo.jpg",
    "labels": ["cat", "dog", "bird", "other"],
    "description": "Select the animal in this photo"
  }
}

{
  "type": "label_text",
  "input": {
    "text": "The new iPhone has amazing battery life and a great camera",
    "categories": ["positive", "negative", "neutral"]
  }
}

{
  "type": "rate_quality",
  "input": {
    "title": "Introduction to Machine Learning",
    "content": "Machine learning is a subset of AI...",
    "criteria": "Rate the accuracy and clarity of this explanation"
  }
}

{
  "type": "verify_fact",
  "input": {
    "claim": "Python was created by Guido van Rossum in 1991",
    "context": "Python is a high-level programming language first released in 1991 by Guido van Rossum."
  }
}

{
  "type": "moderate_content",
  "input": {
    "content": "This product is absolutely terrible, worst purchase ever!",
    "content_type": "product_review",
    "policy_context": "Reject spam, hate speech, and threats. Allow negative opinions."
  }
}

{
  "type": "compare_rank",
  "input": {
    "option_a": "Machine learning uses algorithms to learn from data.",
    "option_b": "ML is when computers figure stuff out from examples.",
    "criteria": "Which explanation is clearer and more professional?"
  }
}

{
  "type": "answer_question",
  "input": {
    "content": "The Eiffel Tower was built in 1889 for the World's Fair...",
    "question": "When was the Eiffel Tower built?",
    "answer_format": "multiple_choice",
    "choices": ["1876", "1889", "1901", "1912"]
  }
}

{
  "type": "transcription_review",
  "input": {
    "audio_url": "https://example.com/recording.mp3",
    "ai_transcript": "Welcome to the podast about artifical inteligence...",
    "language": "en"
  }
}