Little Worker API overview

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.

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

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:

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:

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

Send the request_id when you ask for help at support@thelittleworker.com.

Little Worker's words and Claude's

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

Next steps

• Quickstart: make a worker, give it a task, and read the result.
• Tasks reference: every field of a task, and each route that gives, lists, reads, changes and takes back tasks.