---
title: "Update Mob"
method: PUT
path: "/mobs/{id}"
tags: ["Mobs"]
---

# Update Mob

`PUT /mobs/{id}`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/mobs/{id}`
- Auth: HTTP bearer

Renaming a mob, or changing its head count, writes a record on its
timeline — "Renamed from Merino wethers · Head count set to 1,240 — was
980" — composed on the server, because three write surfaces edit a mob
and only the server sees before and after atomically. An update that
changes neither field writes nothing.

**Archive and restore are this endpoint**: `archived: true` hides the mob
from the map and the lists while its records stay on the property;
`archived: false` brings it back. There is no `/archive` route.
Archiving writes no record.

The owning property cannot be changed — a `farm` relationship sent here
is ignored, so a mob can never be re-parented and take its records with
it. Where the mob IS cannot be set here either; see `moveMob`.

Requires organization edit rights.

## Path parameters

- `id` string, required

## Query parameters

- `include` string

## Request body

- MobUpdateModelAttributes: Flat attributes-adapter request body (Content-Type application/json). Attribute fields live directly under `data` (no nested `attributes` envelope). Every field is optional — a partial write. Equivalent JSON:API (nested) shape: `MobUpdateModel` sent as application/vnd.api+json.
  - `data` object, required
    - `name` string
    - `head_count` integer, nullable
    - `archived` boolean, nullable: `true` archives the mob, `false` restores it.

## Response `200`

Updated

- MobsShowResponseAttributes
  - `data` MobModelAttributes: Single mob in attributes-adapter shape (Accept application/json).
    - `id` string
    - `type` string
    - `slug` string: Unique within its parent (a property per owner; a paddock or mob per property); generated from the name and renamed with it. The old slug keeps resolving. See `resolveLink`.
    - `web_path` string: The address on the web. Present when read directly.
    - `url` string: The whole link; carries the property's `?share=` token when it is shared by link. Present when read directly.
    - `name` string
    - `head_count` integer, nullable: How many head are in the mob, as a number — never a display string. Null is a real state.
    - `withholding` object, nullable: Is the mob under a withholding period or export slaughter interval right now? The latest drench record whose safe-for-slaughter or export date is still ahead, or null. **Derived, not stored.** Read-only.
      - `task_id` string
      - `record_id` string: The DrenchRecord id.
      - `safe_for_slaughter_on` string, date, nullable
      - `export_eligible_on` string, date, nullable
      - `products` string[]
    - `current_paddock_id` string, nullable: Where the mob is right now, derived from the most recent completed record carrying a destination (see `MobModel`). Read-only — move a mob with `moveMob`.
    - `archived` boolean: An archived mob leaves the map and the lists; its records stay on the property.
    - `archived_at` string, date-time, nullable
    - `record_count` integer: Completed rows on this mob — its diary.
    - `open_task_count` integer: Pending rows on this mob.
    - `last_record_at` string, date-time, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `farm` object: Present when include=farm
  - `meta` PaginationMeta
    - `current_page` number
    - `next_page` number, nullable
    - `prev_page` number, nullable

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: A blank name, a name already used on the property (live or archived), or a negative head count

---

[API](https://skmtc.dev/purplegrain/apis/purple-grain-api.md) · [All operations](https://skmtc.dev/purplegrain/apis/purple-grain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/purplegrain/apis/purple-grain-api/revisions/4bedbc1c784c?raw)