---
title: "Create Mob"
method: POST
path: "/mobs"
tags: ["Mobs"]
---

# Create Mob

`POST /mobs`

## Request

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

A name is a valid mob — the head count arrives when someone counts them.
`head_count` is optional. There are no species, class or breed fields
yet; put those in the name (for example "MxBL rams").

Names are unique per property, case-insensitively, across live AND
archived mobs: reusing the name of one that was archived is rejected
here, where a name is being typed, rather than stranding the archived mob
with no way to be restored.

A new mob is not in a paddock. Placement is never set here — it is
derived from the mob's records, so the first `moveMob` is what puts it
somewhere. If this call errors or times out, list the property's mobs
before retrying. Requires organization edit rights.

## Query parameters

- `include` string

## Request body

- MobCreateModelAttributes: Flat attributes-adapter request body (Content-Type application/json). Attribute fields and relationships live directly under `data` (no nested `attributes` / `relationships` envelopes). Each relationship is a resource identifier object ({ id, type }). Equivalent JSON:API (nested) shape: `MobCreateModel` sent as application/vnd.api+json.
  - `data` object, required
    - `name` string, required
    - `head_count` integer, nullable
    - `archived` boolean, nullable
    - `farm` object, nullable, required
      - `id` string, nullable
      - `type` 'farm', nullable

## Response `201`

Created

- 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 missing 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)