# Bulk unassign worker

Bulk unassign worker is a command in the HeadHoncho API. Take one technician or subcontractor off up to 200 jobs.

Page: https://headhoncho.app/docs/api/bulk_unassign_worker | Part of the HeadHoncho API docs: https://headhoncho.app/docs/api | Machine-readable: https://headhoncho.app/docs/api/openapi.json | Everything in one file: https://headhoncho.app/docs/api/llms-full.txt

## The request

Reference for **Bulk unassign worker**, HeadHoncho API v1. It is a command, sent to the base address `https://api.headhoncho.app`.

`POST /api/v1/commands/bulk-unassign-worker`

The key needs the **Jobs** area at **do**. An answered call costs 1 credit; a refusal costs nothing. See [credits](https://headhoncho.app/docs/api/errors#credits).

It runs the app's own command `bulk-unassign-worker`. Send an `Idempotency-Key` header with every call: the same key with the same body returns the first answer and runs nothing twice. See [the model](https://headhoncho.app/docs/api/model#idempotency).

## Parameters

| Name | Kind | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `job_ids` | text, in the JSON body | Yes | Job ids or numbers, 1 to 200, separated by commas. Over the API a JSON list works too. A repeat is read once. | `job_1203, job_1204, 1205` |
| `worker_id` | id, in the JSON body | Yes | From Who am I. | `wrk_7a12` |

## Try it with your key

Paste your key and change the values. The box builds the call as a cURL line and a fetch line, ready to copy. It never sends anything itself.

Paste your key on the web page and it fills a cURL line and a fetch line with your key and the example values. The page never sends the key anywhere. The same lines with a placeholder key are under Examples below.

## What comes back

accepted (true when at least one job changed), requested (how many different jobs you sent), applied (job_id and number of each job that changed), skipped (jobs where nothing needed to change, with why), refused (jobs the app refused, with the app's reason) and not_found (ids that match no job in the companies this credential reaches), then position. One job never stops the others: each runs the app's own single command by itself, with its own history line, and is not undone if another is refused. More than 200 jobs is refused whole, by name.

It never deletes anything. It changes only what the command names, and it writes the change to the job's history with who asked for it.

## Every field in the answer

Types are read from the example answer. Money is a plain number in the company's currency. A time carries its offset from UTC (`Z` is UTC). Ids are opaque text. A field with no line of its own here has its name spelled out; the common fields mean the same on every page.

| Field | Type | Meaning |
| --- | --- | --- |
| `accepted` | true or false | True when the command ran. A command that cannot run is an error instead. |
| `requested` | whole number | The requested. |
| `applied` | list of objects | The applied. |
| `applied[].job_id` | id (text) | The id of the job. |
| `applied[].number` | whole number | The number people say out loud, such as the job number. |
| `skipped` | list | The skipped. |
| `refused` | list of objects | The refused. |
| `refused[].job_id` | id (text) | The id of the job. |
| `refused[].number` | whole number | The number people say out loud, such as the job number. |
| `refused[].reason` | text | The reason given. |
| `not_found` | list | The not found. |
| `position` | whole number | Where the change landed in the event log. Pass it as `after` on a read to see your own write. |

## Partial success

The call is not one transaction. Read applied, skipped, refused and not_found; send the refused ones again after you fix the cause. A whole call replayed with the same Idempotency-Key does nothing twice.

## One credit per job

A call costs one credit for each job it changed. Jobs skipped, refused or not found cost nothing. Before the call runs, your balance must cover every job you sent, or the call is refused no_credits and nothing changes.

## Errors that apply

| Code | Status | What it means |
| --- | --- | --- |
| [`missing_key`](https://headhoncho.app/docs/api/errors#missing_key) | 401 | Send your key as Authorization: Bearer hh_live_... |
| [`unknown_key`](https://headhoncho.app/docs/api/errors#unknown_key) | 401 | That key is not one we issued, or it was revoked. |
| [`no_access`](https://headhoncho.app/docs/api/errors#no_access) | 403 | This credential does not reach that. Ask the person who made it for access. |
| [`read_only`](https://headhoncho.app/docs/api/errors#read_only) | 403 | This credential may read this area but not change it. |
| [`not_found`](https://headhoncho.app/docs/api/errors#not_found) | 404 | No such record in the companies this credential reaches. |
| [`invalid`](https://headhoncho.app/docs/api/errors#invalid) | 422 | Some fields were refused. See fields. |
| [`missing_idempotency_key`](https://headhoncho.app/docs/api/errors#missing_idempotency_key) | 400 | Send an Idempotency-Key header on every command. |
| [`idempotency_mismatch`](https://headhoncho.app/docs/api/errors#idempotency_mismatch) | 409 | This Idempotency-Key was used with a different body. |
| [`idempotency_in_progress`](https://headhoncho.app/docs/api/errors#idempotency_in_progress) | 409 | A command with this Idempotency-Key is still running. Wait a moment and send it again. |
| [`no_credits`](https://headhoncho.app/docs/api/errors#no_credits) | 402 | Out of credits. Top up on Settings › Credits, or turn on auto top-up. |

## Related

- [Bulk change status](https://headhoncho.app/docs/api/bulk_change_status): Move up to 200 jobs to one status. Each move lands in that job's history.
- [Bulk assign worker](https://headhoncho.app/docs/api/bulk_assign_worker): Put one technician or subcontractor on up to 200 jobs. A job that already has them is skipped.
- [Bulk add note](https://headhoncho.app/docs/api/bulk_add_note): Add the same note to up to 200 jobs. It appends to each job's log and never overwrites.
- [Bulk archive jobs](https://headhoncho.app/docs/api/bulk_archive_jobs): File up to 200 finished jobs away. They keep their money and still count in every figure.
- [Bulk unarchive jobs](https://headhoncho.app/docs/api/bulk_unarchive_jobs): Bring up to 200 archived jobs back, as they were.
- [Bulk trash jobs](https://headhoncho.app/docs/api/bulk_trash_jobs): Move up to 200 jobs to Trash, with one reason. They leave every list and figure, and can be restored for 30 days.
- [Bulk restore jobs](https://headhoncho.app/docs/api/bulk_restore_jobs): Bring up to 200 jobs back from Trash, whole: money, history and technicians.
- The same records in the app: [the Jobs panel](https://headhoncho.app/docs/jobs).
- How the API fits together: [the model](https://headhoncho.app/docs/api/model), [API keys](https://headhoncho.app/docs/api/keys), [errors](https://headhoncho.app/docs/api/errors) and [the MCP server](https://headhoncho.app/docs/api/mcp).

## Examples

### Answer

```json
{
  "accepted": true,
  "requested": 3,
  "applied": [
    {
      "job_id": "job_1203",
      "number": 1203
    },
    {
      "job_id": "job_1204",
      "number": 1204
    }
  ],
  "skipped": [],
  "refused": [
    {
      "job_id": "job_1205",
      "number": 1205,
      "reason": "This job is in Trash. Restore it first."
    }
  ],
  "not_found": [],
  "position": 88411
}
```

### cURL

```bash
curl -X POST "https://api.headhoncho.app/api/v1/commands/bulk-unassign-worker" \
  -H "Authorization: Bearer hh_live_..." \
  -H "Idempotency-Key: 6f1d2c9e-1b7a-4c1e-9a52-0d3f8e4b7a10" \
  -H "Content-Type: application/json" \
  -d '{
  "job_ids": "job_1203, job_1204, 1205",
  "worker_id": "wrk_7a12"
}'
```

### Python

```python
import requests
import uuid

response = requests.post(
    "https://api.headhoncho.app/api/v1/commands/bulk-unassign-worker",
    headers={
        "Authorization": "Bearer hh_live_...",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "job_ids": "job_1203, job_1204, 1205",
        "worker_id": "wrk_7a12",
    },
)
response.raise_for_status()
print(response.json())
```

### JavaScript

```javascript
const response = await fetch("https://api.headhoncho.app/api/v1/commands/bulk-unassign-worker", {
  method: "POST",
  headers: {
    Authorization: "Bearer hh_live_...",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "job_ids": "job_1203, job_1204, 1205",
    "worker_id": "wrk_7a12"
  }),
});
const data = await response.json();
console.log(data);
```

### Your AI

```text
Tool: bulk_unassign_worker
Arguments: job_ids (text, required), worker_id (id, required)
Access: do on Jobs
Hints: readOnly=false, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, bulk unassign worker with job_ids job_1203, job_1204, 1205 and worker_id wrk_7a12."
```