Handinger API

Handinger lets you run reusable AI workers from your own code. Use the API to create a worker once and then trigger thousands of tasks against it — synchronously, streamed, on a schedule, or by email.

This site documents the public REST API and the official SDKs. Read the guides if you’re learning, jump to the API Reference if you already know what you need.

Concepts in 30 seconds

• Worker — a reusable agent template, owned by your organization and shared with the members you invite. A worker encodes the agent’s purpose (instructions and model), the side effects it’s allowed to have (MCP integrations, schedules, file access), and the shape of its output (free-form text or a strict JSON schema). Built once, run thousands of times.
• Task — one conversation with a worker. Fire it off for a one-shot answer, or carry the task id forward to continue it like a chat — every follow-up message reuses the prior history, attached files, and tool calls.

A minute-long tour

1. Grab an API key

   Generate a bearer token in the dashboard. The SDKs read it from the HANDINGER_API_KEY env var by default. See authentication.

2. Create a worker

   Pass a natural-language prompt for instant bootstrapping, or supply exact instructions and an outputSchema once you know what you want. See workers.

3. Run a task

   POST /api/tasks with the workerId and the user’s input. Add taskId to a follow-up call to continue the same conversation. See tasks.

Hello, world

TypeScript

import Handinger from '@ramensoft/handinger';

const handinger = new Handinger(); // reads HANDINGER_API_KEY from the env

const worker = await handinger.workers.create({
  prompt:
    'Verify or debunk scientific claims by searching peer-reviewed databases like PubMed and arXiv. Summarize the consensus and cite the strongest evidence on each side.',
});

const result = await handinger.tasks.create({
  workerId: worker.id,
  input: 'Humans only use 10% of their brain.',
});

console.log(result.output_text);
// → "This claim is debunked. Functional brain imaging shows essentially every
//    region activates over the course of a typical day — the '10%' figure has
//    no neuroscience basis."
console.log(result.structured_output);
// → { verdict: 'debunked', summary: '…', citations: ['…'] }

Python

from handinger import Handinger

client = Handinger()  # reads HANDINGER_API_KEY from the env

worker = client.workers.create(
    prompt=(
        "Verify or debunk scientific claims by searching peer-reviewed databases "
        "like PubMed and arXiv. Summarize the consensus and cite the strongest "
        "evidence on each side."
    ),
)

result = client.tasks.create(
    worker_id=worker.id,
    input="Humans only use 10% of their brain.",
)

print(result.output_text)
# → "This claim is debunked. Functional brain imaging shows essentially every
#    region activates over the course of a typical day — the '10%' figure has
#    no neuroscience basis."
print(result.structured_output)
# → {"verdict": "debunked", "summary": "…", "citations": ["…"]}

cURL

WORKER_ID=$(curl -s https://handinger.com/api/workers \
  -H "Authorization: Bearer $HANDINGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Verify or debunk scientific claims by searching peer-reviewed databases like PubMed and arXiv. Summarize the consensus and cite the strongest evidence on each side."
  }' | jq -r '.id')

curl -s https://handinger.com/api/tasks \
  -H "Authorization: Bearer $HANDINGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"workerId\": \"$WORKER_ID\",
    \"input\": \"Humans only use 10% of their brain.\"
  }" | jq '{ output_text, structured_output }'

Prefer Go, Ruby, or the CLI? Every endpoint is documented in all five SDKs in the API reference.

Where to go next

• Quickstart — install an SDK and run your first task.
• Authentication — issue, rotate, and revoke API keys.
• Workers — create, update, and delete worker templates.
• Tasks — run, stream, continue, and archive tasks.
• API Reference — every endpoint and field, with auto-generated SDK signatures.

Need help? Reach us at [email protected] or open an issue against the SDK you’re using.