# Little Worker: how an agent gets access

Little Worker is a to-do list with a team of AI workers. A person gives a
worker a task, the worker does it, asks when it needs a yes, and comes back
Done. The public API lets a program, or an agent, do the same.

- API: https://core.thelittleworker.com/api/v1
- OpenAPI document (needs no key): https://core.thelittleworker.com/api/v1/openapi.json

## 1. Get a key

An agent cannot make a key on its own yet. Ask the person you work for to:

1. Sign in at https://app.thelittleworker.com with an email code, Apple,
   Google or GitHub. It is free with their own AI key.
2. Open Settings, then API Keys, choose Create Key, name it, and copy it.
   The key starts with `lw_key_` and is shown once.
3. Give you the key.

The key acts as that person, in their workspace. Keep it out of logs and
files you share. It stops working when they remove it, leave the workspace,
or delete their account.

## 2. Call the API

Send these headers on every request but the OpenAPI document:

- `x-api-key: lw_key_...` (or `Authorization: Bearer lw_key_...`)
- `Little-Worker-Version: 2026-10-19`
- `Idempotency-Key: <a new UUID>` when you create or change a task, a
  worker or a routine, so a retry does the work once

List the workers:

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

Give a worker a task with `POST /tasks`:

```json
{
  "worker": "worker_...",
  "initial_events": [
    { "type": "user.message", "content": [{ "type": "text", "text": "..." }] }
  ]
}
```

Read it with `GET /tasks/{task_id}`. Its `state.status` is
`not_started`, `working`, `needs_you` or `done`. A task that needs a
yes waits for the person in the app, unless they made the key with Can
allow actions on; then `GET /approvals` lists what waits. Some actions,
such as sending an email, are always the person's.

## 3. When a request is refused

Every refusal has one shape: `{ "type": "error", "error": { "type",
"message", "retryable", "details": { "error_code" } }, "request_id" }`.

- 401 `authentication_error`: the key is missing, wrong or removed. Ask
  the person for a new one. Do not retry with the same key.
- 400 `invalid_request_error`: fix the request as the message says.
- 429 `rate_limit_error`: wait the seconds in `Retry-After`.
- `retryable: true`: the same request may work later.