---
title: Handinger API | Handinger
description: Build, run, and continue Handinger agent workers from your own code.
---

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](/api/index.md) 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](/guides/authentication/index.md).

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](/guides/workers/index.md).

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](/guides/tasks/index.md).

## Hello, world

- [ TypeScript](#tab-panel-56)
- [ Python](#tab-panel-57)
- [ cURL](#tab-panel-58)

```
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: ['…'] }
```

```
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": ["…"]}
```

Terminal window

```
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](/api/index.md).

## Where to go next

- **[Quickstart](/guides/quickstart/index.md)** — install an SDK and run your first task.
- **[Authentication](/guides/authentication/index.md)** — issue, rotate, and revoke API keys.
- **[Workers](/guides/workers/index.md)** — create, update, and delete worker templates.
- **[Tasks](/guides/tasks/index.md)** — run, stream, continue, and archive tasks.
- **[API Reference](/api/index.md)** — every endpoint and field, with auto-generated SDK signatures.

Need help? Reach us at <support@handinger.com> or open an issue against the SDK you’re using.