Skip to content
Get API Key

API reference

Computers

List and read the computers workers use, set up the workspace's Linux computer, and read and stop the work on a computer.

Updated
View as Markdown

A computer is where a worker's commands, browser and files run. A workspace can have one active Linux computer, which Little Worker runs for it, and one Mac that a person paired in the Little Worker Mac app. A task does not pick its computer. A worker's first tool call that needs a computer uses the workspace's own, and the tools that act on a Mac go to the Mac a person paired. A task's computer_id shows the computer it last ran on.

These routes list and read computers, set up the Linux computer, change a computer's name, description, labels and packages, archive or delete one, and read and stop the work on one. A work record is one running stretch of a task on a computer. It opens at the task's first call there. It is stopped once the task's run has ended, or a stop was asked for, and none of its calls is open. The task's next call opens a new record. A task that never uses the computer has no record. Computers explains the two kinds and the work records.

The computer object

Most routes on this page answer a computer, or a list of them. The routes under /work answer work records and queue counts, which have their own fields under Read the work queue and Read a work record. Times are RFC 3339 in UTC, to the millisecond.

Fields

  • typestring
    Always computer.
  • idcomputer id
    The computer's id: computer_ and 32 hex digits. A Linux computer and a Mac have ids of the same form.
  • scopestring
    Always organization: computers are shared by the workspace.
  • namestring
    The computer's name. A Linux computer that was never named is Computer, and a Mac that was never named has the name it was paired under.
  • descriptionstring
    What the computer is for. Empty when unset.
  • metadataobject
    Your own labels for the computer: up to 16 keys of 1 to 64 characters, each with a string value of up to 512.
  • statusstring
    Where the computer stands. A Linux computer is provisioning while it is made, ready when it can take work, stopping and stopped when it is shut down, starting while it starts again, recovering when Little Worker could not confirm a step on the machine, or failed. Little Worker stops a Linux computer after 15 idle minutes and starts it again when a task needs it. A Mac is enrolled while it is paired, and revoked once it is archived or deleted.

    One of provisioning, ready, stopping, stopped, starting, recovering, failed, enrolled, revoked

  • configobject
    Where the computer runs. A Linux computer is cloud and also holds its networking and packages. A Mac is self_hosted and holds only its type.
    Show its 3 fields
    • typestring
      cloud for the Linux computer Little Worker runs for the workspace, self_hosted for a Mac a person paired.

      One of cloud, self_hosted

    • networkingobject
      Only on a cloud computer, and read only. The websites a worker may reach are set on the worker's networking, not here.
      Show its 4 fields
      • typestring
        Always limited.
      • allowed_hostsarray of strings
        Always empty.
      • allow_mcp_serversboolean
        Always true: Little Worker calls apps itself, so the computer never needs to reach them.
      • allow_package_managersboolean
        true when the computer lists packages to install.
    • packagesobject
      Only on a cloud computer. What it installs before work, by package manager.
      Show its 7 fields
      • typestring
        Always packages.
      • aptarray of strings
        The packages installed with apt. Empty when none.
      • cargoarray of strings
        The packages installed with cargo. Empty when none.
      • gemarray of strings
        The packages installed with gem. Empty when none.
      • goarray of strings
        The packages installed with go. Empty when none.
      • npmarray of strings
        The packages installed with npm. Empty when none.
      • piparray of strings
        The packages installed with pip. Empty when none.
  • created_attime
    When the computer was made, or the Mac was paired.
  • updated_attime
    When the computer's record last changed. It moves each time the computer reports in, so it does not mean someone edited the computer.
  • archived_attime or null
    When the computer was archived. null while it is not.
Computer object
{
  "type": "computer",
  "id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "scope": "organization",
  "name": "Workspace computer",
  "description": "Runs the shop's tasks.",
  "metadata": {
    "team": "ops"
  },
  "status": "ready",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allowed_hosts": [],
      "allow_mcp_servers": true,
      "allow_package_managers": true
    },
    "packages": {
      "type": "packages",
      "apt": [
        "graphviz"
      ],
      "cargo": [],
      "gem": [],
      "go": [],
      "npm": [],
      "pip": [
        "pandas==2.2.0"
      ]
    }
  },
  "created_at": "2026-10-20T09:14:02.331Z",
  "updated_at": "2026-10-25T08:40:17.904Z",
  "archived_at": null
}

List computers

GET/computers

List the computers in the key's workspace: the Linux computer when there is one, and the Mac a person paired. They come newest first by default. Archived computers are left out unless you ask for them. On a shared workspace, a Mac is listed only for the person who paired it.

Query parameters

  • limitinteger
    How many to answer, 1 to 1,000. The default is 20.
  • pagestring
    The next_page of the answer before, to read the next page.
  • orderstring
    desc, newest first (the default), or asc, oldest first.

    One of desc, asc

  • created_at[gt]time
    Only those made after this time, an RFC 3339 time compared to the millisecond the answer shows. created_at[gte], created_at[lt] and created_at[lte] work the same way.
  • include_archivedstring
    true lists archived computers too. The default is false.

    One of true, false

Returns

A list: data holds the computers, and next_page is the page to send for the next ones (null on the last page).

Errors

StatusTypeWhen
400invalid_request_errorA query value is not valid, such as a limit outside 1 to 1,000 or an include_archived that is not true or false (error_code validation_error). page is not a page this list gave with the same order and created_at filters (error_code invalid_cursor). Read the first page again.
401authentication_errorThe key is missing, removed, or not a key. Send it in x-api-key.
429rate_limit_errorThe workspace made too many requests this minute. Wait the seconds in Retry-After, then try again.
curl "https://core.thelittleworker.com/api/v1/computers?limit=10" \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
Response200
{
  "data": [
    {
      "type": "computer",
      "id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
      "scope": "organization",
      "name": "Workspace computer",
      "description": "Runs the shop's tasks.",
      "metadata": {
        "team": "ops"
      },
      "status": "ready",
      "config": {
        "type": "cloud",
        "networking": {
          "type": "limited",
          "allowed_hosts": [],
          "allow_mcp_servers": true,
          "allow_package_managers": true
        },
        "packages": {
          "type": "packages",
          "apt": [
            "graphviz"
          ],
          "cargo": [],
          "gem": [],
          "go": [],
          "npm": [],
          "pip": [
            "pandas==2.2.0"
          ]
        }
      },
      "created_at": "2026-10-20T09:14:02.331Z",
      "updated_at": "2026-10-25T08:40:17.904Z",
      "archived_at": null
    },
    {
      "type": "computer",
      "id": "computer_9b7e3c1a5d2f4a8e8c6b0d4f2a1e7c35",
      "scope": "organization",
      "name": "Sam's MacBook Pro",
      "description": "",
      "metadata": {},
      "status": "enrolled",
      "config": {
        "type": "self_hosted"
      },
      "created_at": "2026-10-12T15:22:48.017Z",
      "updated_at": "2026-10-25T16:03:51.642Z",
      "archived_at": null
    }
  ],
  "next_page": null
}

Set up the Linux computer

POST/computers

Set up the workspace's Linux computer, with its name and the packages it installs before work. A workspace has one active Linux computer, so a second call is refused until the first is archived or deleted. A Mac cannot be made here: a person pairs it in the Mac app.

The answer comes after the machine is made, so status is normally ready. It is recovering when Little Worker could not confirm the machine or could not finish setting it up. Read the computer again to see it change. Packages are installed when the computer is made, started or recreated.

Body

  • namestringRequired
    The computer's name, 1 to 256 characters.
  • configobjectRequired
    Where the computer runs.
    Show its 3 fields
    • typestringRequired
      cloud for the Linux computer. self_hosted is refused: a Mac joins when a person pairs it.

      One of cloud, self_hosted

    • packagesobject
      What to install before work. A manager you leave out lists nothing.
      Show its 7 fields
      • typestring
        Always packages when you send it. A computer's own packages has it, so you may send that back as it is.
      • aptarray of strings
        The packages to install with apt: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or @ and has no spaces, quotes or shell characters, with a version if you want one, such as pandas==2.2.0. Left out, none.
      • cargoarray of strings
        The packages to install with cargo: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or @ and has no spaces, quotes or shell characters, with a version if you want one, such as pandas==2.2.0. Left out, none.
      • gemarray of strings
        The packages to install with gem: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or @ and has no spaces, quotes or shell characters, with a version if you want one, such as pandas==2.2.0. Left out, none.
      • goarray of strings
        The packages to install with go: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or @ and has no spaces, quotes or shell characters, with a version if you want one, such as pandas==2.2.0. Left out, none.
      • npmarray of strings
        The packages to install with npm: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or @ and has no spaces, quotes or shell characters, with a version if you want one, such as pandas==2.2.0. Left out, none.
      • piparray of strings
        The packages to install with pip: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or @ and has no spaces, quotes or shell characters, with a version if you want one, such as pandas==2.2.0. Left out, none.
    • networkingobject
      Refused. A computer's networking is read only; set the websites a worker may reach on the worker.
  • descriptionstring
    What the computer is for, up to 2,048 characters.
  • metadataobject
    Your own labels: up to 16 keys of 1 to 64 characters, each with a string value of up to 512.
  • scopestring
    organization, the only scope a computer has. account is refused.

    One of organization, account

Returns

200 and the computer.

Errors

StatusTypeWhen
400invalid_request_errorA field is missing or not valid, or one is refused (error_code validation_error): config.type is self_hosted, scope is account, or config.networking is sent. message says which.
401authentication_errorThe key is missing, removed, or not a key. Send it in x-api-key.
409conflict_errorThe workspace already has a Linux computer (error_code computer_conflict). Archive or delete it before you make another. A workspace whose subscription does not include a computer on Little Worker's servers is refused with error_code conflict and the message A hosted computer is not available.
429rate_limit_errorThe workspace made too many requests this minute. Wait the seconds in Retry-After, then try again.
curl "https://core.thelittleworker.com/api/v1/computers" \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19" \
  -H "content-type: application/json" \
  -d '{
  "name": "Workspace computer",
  "description": "Runs the shop'\''s tasks.",
  "config": {
    "type": "cloud",
    "packages": {
      "apt": [
        "graphviz"
      ],
      "pip": [
        "pandas==2.2.0"
      ]
    }
  },
  "metadata": {
    "team": "ops"
  }
}'
Response200
{
  "type": "computer",
  "id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "scope": "organization",
  "name": "Workspace computer",
  "description": "Runs the shop's tasks.",
  "metadata": {
    "team": "ops"
  },
  "status": "ready",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allowed_hosts": [],
      "allow_mcp_servers": true,
      "allow_package_managers": true
    },
    "packages": {
      "type": "packages",
      "apt": [
        "graphviz"
      ],
      "cargo": [],
      "gem": [],
      "go": [],
      "npm": [],
      "pip": [
        "pandas==2.2.0"
      ]
    }
  },
  "created_at": "2026-10-20T09:14:02.331Z",
  "updated_at": "2026-10-20T09:14:04.870Z",
  "archived_at": null
}

Read a computer

GET/computers/{computer_id}

Read one computer as it stands now, archived or not. A deleted computer is gone.

Path parameters

  • computer_idcomputer idRequired
    The computer, such as computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21. A Mac has an id of the same form.

Returns

The computer.

Errors

StatusTypeWhen
400invalid_request_errorcomputer_id is not a computer id. error_code is validation_error.
401authentication_errorThe key is missing, removed, or not a key. Send it in x-api-key.
404not_found_errorNo computer in the key's workspace has this id (Computer not found.), or it was deleted. On a shared workspace, a Mac that another person paired is not found either.
429rate_limit_errorThe workspace made too many requests this minute. Wait the seconds in Retry-After, then try again.
curl https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21 \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
Response200
{
  "type": "computer",
  "id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "scope": "organization",
  "name": "Workspace computer",
  "description": "Runs the shop's tasks.",
  "metadata": {
    "team": "ops"
  },
  "status": "ready",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allowed_hosts": [],
      "allow_mcp_servers": true,
      "allow_package_managers": true
    },
    "packages": {
      "type": "packages",
      "apt": [
        "graphviz"
      ],
      "cargo": [],
      "gem": [],
      "go": [],
      "npm": [],
      "pip": [
        "pandas==2.2.0"
      ]
    }
  },
  "created_at": "2026-10-20T09:14:02.331Z",
  "updated_at": "2026-10-25T08:40:17.904Z",
  "archived_at": null
}

Change a computer

POST/computers/{computer_id}

Change a computer's name, description, labels or packages. A field left out stays as it was. A metadata key with a string is set, a key set to null is removed, and keys left out stay. An archived computer takes no change.

A Linux computer's packages replace the ones it had, so send every package you want to keep. A manager you leave out is emptied. The new packages are installed the next time the computer starts or is recreated. A Mac installs no packages.

Path parameters

  • computer_idcomputer idRequired
    The computer, such as computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21. A Mac has an id of the same form.

Body

  • namestring
    A new name, 1 to 256 characters.
  • descriptionstring
    A new description, up to 2,048 characters.
  • metadataobject
    Labels to set, up to 16 keys of 1 to 64 characters, each with a string value of up to 512 or null. A key set to null is removed. The computer may not hold more than 16 keys after the change.
  • configobject
    Settings of where the computer runs.
    Show its 3 fields
    • packagesobject
      The packages to install, which replace the old ones. Linux computer only.
      Show its 7 fields
      • typestring
        Always packages when you send it. A computer's own packages has it, so you may send that back as it is.
      • aptarray of strings
        The packages to install with apt: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or @ and has no spaces, quotes or shell characters, with a version if you want one, such as pandas==2.2.0. Left out, none.
      • cargoarray of strings
        The packages to install with cargo: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or @ and has no spaces, quotes or shell characters, with a version if you want one, such as pandas==2.2.0. Left out, none.
      • gemarray of strings
        The packages to install with gem: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or @ and has no spaces, quotes or shell characters, with a version if you want one, such as pandas==2.2.0. Left out, none.
      • goarray of strings
        The packages to install with go: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or @ and has no spaces, quotes or shell characters, with a version if you want one, such as pandas==2.2.0. Left out, none.
      • npmarray of strings
        The packages to install with npm: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or @ and has no spaces, quotes or shell characters, with a version if you want one, such as pandas==2.2.0. Left out, none.
      • piparray of strings
        The packages to install with pip: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or @ and has no spaces, quotes or shell characters, with a version if you want one, such as pandas==2.2.0. Left out, none.
    • typestring
      If you send it, it must be the computer's own config.type. It cannot change.

      One of cloud, self_hosted

    • networkingobject
      Refused. A computer's networking is read only; set the websites a worker may reach on the worker.

Returns

The computer, changed.

Errors

StatusTypeWhen
400invalid_request_errorA field is not valid, or one is refused (error_code validation_error): config.networking is sent, config.type is not the computer's own, config.packages is sent for a Mac, or the labels would pass 16. message says which.
400invalid_request_errorThe computer is archived and takes no change (error_code computer_archived).
401authentication_errorThe key is missing, removed, or not a key. Send it in x-api-key.
404not_found_errorNo computer in the key's workspace has this id (Computer not found.), or it was deleted. On a shared workspace, a Mac that another person paired is not found either.
429rate_limit_errorThe workspace made too many requests this minute. Wait the seconds in Retry-After, then try again.
curl "https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21" \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19" \
  -H "content-type: application/json" \
  -d '{
  "description": "Runs the shop'\''s tasks.",
  "metadata": {
    "team": "ops"
  },
  "config": {
    "packages": {
      "apt": [
        "graphviz"
      ],
      "pip": [
        "pandas==2.2.0"
      ]
    }
  }
}'
Response200
{
  "type": "computer",
  "id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "scope": "organization",
  "name": "Workspace computer",
  "description": "Runs the shop's tasks.",
  "metadata": {
    "team": "ops"
  },
  "status": "ready",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allowed_hosts": [],
      "allow_mcp_servers": true,
      "allow_package_managers": true
    },
    "packages": {
      "type": "packages",
      "apt": [
        "graphviz"
      ],
      "cargo": [],
      "gem": [],
      "go": [],
      "npm": [],
      "pip": [
        "pandas==2.2.0"
      ]
    }
  },
  "created_at": "2026-10-20T09:14:02.331Z",
  "updated_at": "2026-10-25T08:40:17.904Z",
  "archived_at": null
}

Archive a computer

POST/computers/{computer_id}/archive

Archive a computer you no longer want to use. It takes no new work, and lists leave it out unless you ask for include_archived=true. It cannot be undone. Archiving a computer twice changes nothing. A computer with work still open on it cannot be archived.

The Linux computer is stopped and its disk is kept, and it frees the workspace's place for another. A Mac's access is taken away, so pairing it again makes a new Mac.

Path parameters

  • computer_idcomputer idRequired
    The computer, such as computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21. A Mac has an id of the same form.

Returns

The computer, with archived_at set. A Linux computer that was running is stopped as it is archived, so its status reads stopped, or recovering when Little Worker could not confirm that the machine stopped. One that was not running keeps its status. A Mac's status reads revoked.

Errors

StatusTypeWhen
400invalid_request_errorcomputer_id is not a computer id. error_code is validation_error.
401authentication_errorThe key is missing, removed, or not a key. Send it in x-api-key.
404not_found_errorNo computer in the key's workspace has this id (Computer not found.), or it was deleted. On a shared workspace, a Mac that another person paired is not found either.
409conflict_errorA work record on the computer is not stopped yet, and a stopping one counts (error_code computer_busy). Stop that work with Stop work on a computer, then archive the computer.
429rate_limit_errorThe workspace made too many requests this minute. Wait the seconds in Retry-After, then try again.
curl "https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21/archive" \
  -X POST \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
Response200
{
  "type": "computer",
  "id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "scope": "organization",
  "name": "Workspace computer",
  "description": "Runs the shop's tasks.",
  "metadata": {
    "team": "ops"
  },
  "status": "stopped",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allowed_hosts": [],
      "allow_mcp_servers": true,
      "allow_package_managers": true
    },
    "packages": {
      "type": "packages",
      "apt": [
        "graphviz"
      ],
      "cargo": [],
      "gem": [],
      "go": [],
      "npm": [],
      "pip": [
        "pandas==2.2.0"
      ]
    }
  },
  "created_at": "2026-10-20T09:14:02.331Z",
  "updated_at": "2026-10-25T17:12:04.126Z",
  "archived_at": "2026-10-25T17:12:03.418Z"
}

Delete a computer

DEL/computers/{computer_id}

Delete a computer for good. It does not need to be archived first. Its access is taken away, and a Linux computer's machine is ended and its place is free for another. Reads of it answer 404 afterwards. A computer with a work record on it, from any task, cannot be deleted, even after the task ends. Archive it instead.

Path parameters

  • computer_idcomputer idRequired
    The computer, such as computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21. A Mac has an id of the same form.

Returns

type is computer_deleted, with the computer's id.

Errors

StatusTypeWhen
400invalid_request_errorcomputer_id is not a computer id. error_code is validation_error.
401authentication_errorThe key is missing, removed, or not a key. Send it in x-api-key.
404not_found_errorNo computer in the key's workspace has this id (Computer not found.), or it was deleted. On a shared workspace, a Mac that another person paired is not found either.
409conflict_errorThe computer has a work record, from any task and in any state (error_code computer_busy). Archive it instead.
429rate_limit_errorThe workspace made too many requests this minute. Wait the seconds in Retry-After, then try again.
curl "https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21" \
  -X DELETE \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
Response200
{
  "type": "computer_deleted",
  "id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21"
}

List work on a computer

GET/computers/{computer_id}/work

List the work records of a computer, newest first by default. A record is one running stretch of one task on the computer, open or over. An archived computer lists its records too.

Path parameters

  • computer_idcomputer idRequired
    The computer, such as computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21. A Mac has an id of the same form.

Query parameters

  • limitinteger
    How many to answer, 1 to 1,000. The default is 20.
  • pagestring
    The next_page of the answer before, to read the next page.
  • orderstring
    desc, newest first (the default), or asc, oldest first.

    One of desc, asc

  • created_at[gt]time
    Only those made after this time, an RFC 3339 time compared to the millisecond the answer shows. created_at[gte], created_at[lt] and created_at[lte] work the same way.

Returns

A list: data holds the work records, as Read a work record shows them, and next_page is the page to send for more (null on the last page).

Errors

StatusTypeWhen
400invalid_request_errorA filter is not valid, such as a limit outside 1 to 1,000, or computer_id is not a computer id (error_code validation_error). page is not a page this list gave with the same order and created_at filters (error_code invalid_cursor). Read the first page again.
401authentication_errorThe key is missing, removed, or not a key. Send it in x-api-key.
404not_found_errorNo computer in the key's workspace has this id (Computer not found.), or it was deleted. On a shared workspace, a Mac that another person paired is not found either.
429rate_limit_errorThe workspace made too many requests this minute. Wait the seconds in Retry-After, then try again.
curl "https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21/work?limit=20" \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
Response200
{
  "data": [
    {
      "type": "work",
      "id": "work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40",
      "computer_id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
      "data": {
        "type": "task",
        "id": "task_01JA8Z6Q4M3T9V2K7X5R1B0C8D"
      },
      "state": "active",
      "secret": null,
      "metadata": {
        "source": "crm"
      },
      "created_at": "2026-10-25T16:04:14.882Z",
      "acknowledged_at": "2026-10-25T16:04:15.140Z",
      "started_at": "2026-10-25T16:04:15.395Z",
      "latest_heartbeat_at": "2026-10-25T16:04:25.402Z",
      "stop_requested_at": null,
      "stopped_at": null
    }
  ],
  "next_page": null
}

Read the work queue

GET/computers/{computer_id}/work/stats

Count the work that waits on a computer, and say whether its runner is listening for it. A runner is the program on the computer that takes a worker's calls. This works on an archived computer too.

Path parameters

  • computer_idcomputer idRequired
    The computer, such as computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21. A Mac has an id of the same form.

Returns

type is work_queue_stats, with these fields.

  • typestring
    Always work_queue_stats.
  • depthinteger
    How many records are queued: no runner has taken a call yet.
  • pendinginteger
    How many records are starting: a runner took a call that is not running yet.
  • oldest_queued_attime or null
    When the oldest queued or starting record opened. null when none waits.
  • runners_pollinginteger
    1 when the computer's runner has been in touch in the last 30 seconds, and 0 when it has not. A computer has one runner.

Errors

StatusTypeWhen
400invalid_request_errorcomputer_id is not a computer id. error_code is validation_error.
401authentication_errorThe key is missing, removed, or not a key. Send it in x-api-key.
404not_found_errorNo computer in the key's workspace has this id (Computer not found.), or it was deleted. On a shared workspace, a Mac that another person paired is not found either.
429rate_limit_errorThe workspace made too many requests this minute. Wait the seconds in Retry-After, then try again.
curl https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21/work/stats \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
Response200
{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "runners_polling": 1
}

Read a work record

GET/computers/{computer_id}/work/{work_id}

Read one work record. A record opens at a task's first call on the computer. It is stopped once the task's run has ended, or a stop was asked for, and none of its calls is open. It reports what ran. The calls under it are what the computer runs.

Path parameters

  • computer_idcomputer idRequired
    The computer, such as computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21. A Mac has an id of the same form.
  • work_idwork idRequired
    The work record, such as work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40.

Returns

type is work, with these fields.

  • typestring
    Always work.
  • idwork id
    The record's id: work_ and 32 hex digits.
  • computer_idcomputer id
    The computer the work is on.
  • dataobject
    The task the work is for.
    Show its 2 fields
    • typestring
      Always task.
    • idtask id
      The task.
  • statestring
    Where the work is. queued waits for the computer, starting was taken by the computer, active has had a call start running, stopping was told to stop and waits for its open calls to end, and stopped is over. A record only moves forward.

    One of queued, starting, active, stopping, stopped

  • secretstring or null
    Always null. The computer's own runner holds a secret; no route here answers one.
  • metadataobject
    Your own labels for the record. It starts with the task's labels. Up to 16 keys of 1 to 64 characters, each with a string value of up to 512.
  • created_attime
    When the record opened: at the task's first call on the computer.
  • acknowledged_attime or null
    When the computer took the first call (starting). null until then. Each step sets its time once.
  • started_attime or null
    When the first call started running (active). null until then.
  • latest_heartbeat_attime or null
    When the computer last reported that it was still on the work. null until it does.
  • stop_requested_attime or null
    When a stop was asked for (stopping). null until then.
  • stopped_attime or null
    When the work was over (stopped). null while it is not.

Errors

StatusTypeWhen
400invalid_request_errorcomputer_id or work_id is not an id of its kind. error_code is validation_error.
401authentication_errorThe key is missing, removed, or not a key. Send it in x-api-key.
404not_found_errorThe computer has no record with this id (Work not found.), or the computer is not found (Computer not found.), for the reasons under Read a computer.
429rate_limit_errorThe workspace made too many requests this minute. Wait the seconds in Retry-After, then try again.
curl https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21/work/work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40 \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
Response200
{
  "type": "work",
  "id": "work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40",
  "computer_id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "data": {
    "type": "task",
    "id": "task_01JA8Z6Q4M3T9V2K7X5R1B0C8D"
  },
  "state": "active",
  "secret": null,
  "metadata": {
    "source": "crm"
  },
  "created_at": "2026-10-25T16:04:14.882Z",
  "acknowledged_at": "2026-10-25T16:04:15.140Z",
  "started_at": "2026-10-25T16:04:15.395Z",
  "latest_heartbeat_at": "2026-10-25T16:04:25.402Z",
  "stop_requested_at": null,
  "stopped_at": null
}

Change a work record

POST/computers/{computer_id}/work/{work_id}

Change a work record's labels. A key with a string is set, a key set to null is removed, and keys left out stay. Without metadata, nothing changes.

Path parameters

  • computer_idcomputer idRequired
    The computer, such as computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21. A Mac has an id of the same form.
  • work_idwork idRequired
    The work record, such as work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40.

Body

  • metadataobject
    Labels to set, up to 16 keys of 1 to 64 characters, each with a string value of up to 512 or null. A key set to null is removed. The record may not hold more than 16 keys after the change.

Returns

The work record, as Read a work record shows it.

Errors

StatusTypeWhen
400invalid_request_errorA field is not valid, such as a metadata that would hold more than 16 keys, or an id is not of its kind (error_code validation_error).
401authentication_errorThe key is missing, removed, or not a key. Send it in x-api-key.
404not_found_errorThe computer has no record with this id (Work not found.), or the computer is not found (Computer not found.), for the reasons under Read a computer.
429rate_limit_errorThe workspace made too many requests this minute. Wait the seconds in Retry-After, then try again.
curl "https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21/work/work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40" \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19" \
  -H "content-type: application/json" \
  -d '{
  "metadata": {
    "source": "crm"
  }
}'
Response200
{
  "type": "work",
  "id": "work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40",
  "computer_id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "data": {
    "type": "task",
    "id": "task_01JA8Z6Q4M3T9V2K7X5R1B0C8D"
  },
  "state": "active",
  "secret": null,
  "metadata": {
    "source": "crm"
  },
  "created_at": "2026-10-25T16:04:14.882Z",
  "acknowledged_at": "2026-10-25T16:04:15.140Z",
  "started_at": "2026-10-25T16:04:15.395Z",
  "latest_heartbeat_at": "2026-10-25T16:04:25.402Z",
  "stop_requested_at": null,
  "stopped_at": null
}

Stop work on a computer

POST/computers/{computer_id}/work/{work_id}/stop

Stop the task that a work record is for. The task's run is asked to stop, on every computer it uses. Other tasks on the computer keep running. Stopping a record that is stopped answers it as it is.

By default the calls the computer already took finish, and the record reads stopping until they report. With force, every open call ends now: one the computer had not taken is cancelled, and one it had taken is outcome_unknown, because nobody can say what it did. The answer reads stopped. A taken call whose outcome is unknown holds the Linux computer for review.

Path parameters

  • computer_idcomputer idRequired
    The computer, such as computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21. A Mac has an id of the same form.
  • work_idwork idRequired
    The work record, such as work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40.

Body

  • forceboolean
    true ends every open call now. Left out or false, calls the computer already took finish first. Send {} for the gentle stop.

Returns

The work record, as Read a work record shows it. Its state is stopping after a gentle stop with calls still open, and stopped after a forced stop or when no call was open.

Errors

StatusTypeWhen
400invalid_request_errorAn id is not of its kind, force is not true or false, or the body holds another field (error_code validation_error).
401authentication_errorThe key is missing, removed, or not a key. Send it in x-api-key.
404not_found_errorThe computer has no record with this id (Work not found.), or the computer is not found (Computer not found.), for the reasons under Read a computer.
429rate_limit_errorThe workspace made too many requests this minute. Wait the seconds in Retry-After, then try again.
curl "https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21/work/work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40/stop" \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19" \
  -H "content-type: application/json" \
  -d '{}'
Response200
{
  "type": "work",
  "id": "work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40",
  "computer_id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "data": {
    "type": "task",
    "id": "task_01JA8Z6Q4M3T9V2K7X5R1B0C8D"
  },
  "state": "stopping",
  "secret": null,
  "metadata": {
    "source": "crm"
  },
  "created_at": "2026-10-25T16:04:14.882Z",
  "acknowledged_at": "2026-10-25T16:04:15.140Z",
  "started_at": "2026-10-25T16:04:15.395Z",
  "latest_heartbeat_at": "2026-10-25T16:04:25.402Z",
  "stop_requested_at": "2026-10-25T16:09:41.226Z",
  "stopped_at": null
}

Type a few words, like “give a task” or “errors”.