# Little Worker API overview

Give work to your workers from your own programs, follow it as it happens, and read what comes back.

The Little Worker API lets your own programs work with your workers over plain HTTPS. A program can give a worker a task, follow the task while the worker does it, answer what the worker asks, and read the result. These are the same things a person does in the app, so a task given with the API shows up in the app too.

The API is shaped like Claude Managed Agents, with Little Worker's words for things. If you have built on Managed Agents, most of what you know carries over: an agent is a worker, and a session is a task.

> [!TIP]
> New here? The [Quickstart](/get-started/quickstart) gives a worker its first task in about five minutes.

## When to use it

Use the API when the work starts somewhere other than the app, or when its result goes somewhere else:

- Give a task from a script, a form, or another product, the moment something happens there.
- Show a task's progress, and its answer, in a screen of your own.
- Read many finished tasks at once and send back the ones that are not right.
- Keep a record of what each task cost and which app actions were allowed.

## How a task works

A task is one piece of work by one worker. Every task goes the same way:

1. **You give it.** `POST /tasks` names the worker, and a `user.message` says, in plain words, what you want. The task is `running`.
2. **The worker works.** Each thing the worker does, such as a message, a tool it uses, or a stop, is an event you can list or follow live.
3. **The worker stops.** The task is `idle`, and `stop_reason` says why. When it waits for you, `stop_reason` is `requires_action`, `state.status` is `needs_you`, and `state.needs` says what for: to `allow` an action, to `answer` a question, to `help` after a failure, or to `look` at work its own check found short.
4. **The work comes back.** `state.status` is `done`. `result_summary` holds one line about the result, and the worker's full answer is its last `worker.message` event.
5. **You check it.** If the result is not right, send it back with what to change, and the worker works on it again.

A task has two statuses side by side. `status` is a Claude session's: `running`, `idle` or `rescheduling`. `state` says the same in the words the app shows: `not_started`, `working`, `needs_you` or `done`.

## The main ideas

| Name | What it is | Where |
| --- | --- | --- |
| Worker | A helper with a name and instructions in plain words. A worker does one task at a time, and each change to it makes a new version. | `/workers` |
| Task | One piece of work by one worker, from the moment you give it to its result. | [`/tasks`](/api/tasks) |
| Event | One thing that happened in a task, in order: a message, a tool used, a stop. | `/tasks/{task_id}/events` |
| Approval | A worker asking before it takes an action that asks first. | `/approvals` |
| Routine | Work that repeats by itself. Each time it runs, it gives its worker a task. | `/routines` |
| App | An app a person connected, and what workers may do in it. | `/apps` |
| Computer | The workers' Linux computer, or a Mac a person paired. | `/computers` |
| Memory store | Notes at paths that a worker reads and writes, from task to task, with every change kept. | `/memory_stores` |
| Password set | Passwords a task signs in with. A value goes in and never comes back out. | `/password_sets` |
| File and skill | A file you upload for a task, and a skill that teaches a worker a way of working. | `/files`, `/skills` |
| Receipt | What one run of a task cost, and which app actions were decided. | [`/tasks/{task_id}/receipts`](/api/tasks#read-what-a-task-cost) |

A run is one stretch of work inside a task. A task has a new run each time it starts again, such as after you send a message or send the result back.

## Making a request

Every request goes to one base URL, carries your key, and names the version of the API it was written for:

```bash
curl https://core.thelittleworker.com/api/v1/workers \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
```

- **Base URL.** `https://core.thelittleworker.com/api/v1`.
- **Key.** Make one on the web in Settings, then API Keys. A key acts as you, in your workspace. Send it in `x-api-key`, or as `Authorization: Bearer <key>`.
- **Version.** `Little-Worker-Version: 2026-10-19` on every request. Without it, or with any other value, the answer is `400`, so a change to the API never surprises a program written for an older one.
- **JSON in, JSON out.** Field names are `snake_case`, times are RFC 3339 in UTC, and every id starts with its kind, such as `worker_` or `task_`. Money is `{ "amount": "250", "currency": "USD" }`, in whole US cents.
- **Lists.** A list answers `{ "data": [...], "next_page": ... }`, newest first; `?order=asc` reads oldest first, and a task's events come oldest first. Send `next_page` back as `?page=` for more, until it is `null`.
- **Retries.** Send an `Idempotency-Key` header, a UUID, with `POST /tasks`, `POST /tasks/{task_id}/events`, and the routes that make or change workers and routines. A retry with the same key does the work once. Other routes ignore it.
- **Limits.** A workspace, across all its keys, may make 1,200 reads and 300 writes a minute, and hold 10 open event streams. Past a limit the answer is `429`, with `Retry-After` in seconds.

The whole API is also described as an OpenAPI document at `https://core.thelittleworker.com/api/v1/openapi.json`, which needs no key.

## Errors

Every refusal has the same shape, the shape of Claude's errors. `error.type` names the kind of refusal, `message` says what to change, `retryable` says whether the same request may work later, and `details.error_code` is the exact reason:

```json
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Worker not found.",
    "retryable": false,
    "details": { "error_code": "not_found" }
  },
  "request_id": "request_3f2a9c1d7e5b4a8f9d0c2e4b6a8d1f3c"
}
```

| Status | `error.type` |
| --- | --- |
| 400 | `invalid_request_error` |
| 401 | `authentication_error` |
| 403 | `permission_error` |
| 404 | `not_found_error` |
| 409 | `conflict_error` |
| 413 | `request_too_large` |
| 429 | `rate_limit_error` |
| 500 | `api_error` |
| 503 | `overloaded_error` |

Send the `request_id` when you ask for help at [support@thelittleworker.com](mailto:support@thelittleworker.com).

## Little Worker's words and Claude's

| Little Worker | Claude Managed Agents |
| --- | --- |
| worker | agent |
| task | session |
| event | event |
| `worker.*` events | `agent.*` events |
| `task.status_*` events | `session.status_*` events |
| approval (`user.approval`) | tool confirmation (`user.tool_confirmation`) |
| app | MCP server |
| memory store | memory store |
| note | memory |
| routine | deployment |
| computer | environment |
| password set | vault |
| password | credential |
| file | file |
| skill | skill |
| receipt | none: Little Worker's own. Claude's `usage` is on the task as well |
| API key | API key |

One task is one session: giving a task starts its work, and its events are the session's events.

## Next steps

- [Quickstart](/get-started/quickstart): make a worker, give it a task, and read the result.
- [Tasks reference](/api/tasks): every field of a task, and each route that gives, lists, reads, changes and takes back tasks.