---
title: "Read a shared treatment register"
method: GET
path: "/shares/{token}"
tags: ["Public", "Shared records"]
---

# Read a shared treatment register

`GET /shares/{token}`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/shares/{token}`
- Auth: one of:
  - none
  - HTTP bearer

Public (no account): the token in the link IS the credential. Returns only the register the
owner chose to export, per mob with an `under_withholding` / `clear` status and the safe dates,
who shared it and when the link expires. No ids, emails or phone numbers. The rows are rebuilt
from the records as they are now. The first successful read stamps the share as opened.

* **404**: not a link (unknown, malformed, or one whose email or text never went). One shape
  for all of them.
* **410**: a link that was real and has ended. Body `{ "state": "expired" | "revoked",
  "shared_by": "<name>" }` and nothing else; the page says "This link has expired." / "This
  link has been revoked." and "Ask {shared_by} to send a new one."
* **429**: rate limited per IP and per token.

Never cached or indexed (`Cache-Control: no-store`, `X-Robots-Tag: noindex`). Refused (403) to
an api or MCP bearer token; the web page and anonymous callers pass.

## Path parameters

- `token` string, required

## Response `200`

The register.

- SharedRecordsResponse: What `/s/<token>` shows for a live link: only the register the owner chose to export, with no ids, emails or phone numbers. Plain JSON, same for both Accept types.
  - `state` 'active', required
  - `kind` 'register' | 'nvd' | 'spray' | 'paddock-inputs', required
  - `title` string, required
  - `property` object, required
    - `name` string
    - `pic` string, nullable
  - `range` object, required
    - `from` string, date
    - `to` string, date
  - `shared_by` string, required: The sender's name (never an email or phone), or `the sender` when they have none.
  - `expires_at` string, date-time, required
  - `formats` string[], required
  - `summary` union, required
    - TreatmentRegisterSummary: What the Export dialog's count line, amber note and empty states read.
      - `drenches` integer, required: The number of records (kept under its old name). The count line says `drench`, `treatment` or `record` by what they are.
      - `records` integer
      - `mobs` integer, required
      - `products` integer, required: Rows (one per product).
      - `line` string, required
      - `not_recorded` object, required: How many are missing, per field. A product's own fields count once per row; `head`, `location`, `treated_by` and the two safe dates once per drench. Only fields missing somewhere appear.
      - `under_withholding_mobs` integer, required
      - `empty` boolean, required
      - `empty_reason` 'no_drenches' | 'none_under_withholding' | 'null', nullable, required
    - PaddockRegisterSummary: What the Export dialog's count line, amber note and empty states read, for a paddock register.
      - `records` integer, required
      - `paddocks` integer, required
      - `products` integer, required: Rows (one per product line).
      - `line` string, required
      - `not_recorded` object, required
      - `under_withholding_paddocks` integer, required
      - `empty` boolean, required
      - `empty_reason` 'no_sprays' | 'no_inputs' | 'null', nullable, required
  - `mobs` TreatmentRegisterMob[]: The treatment register and the NVD list only.
    - `id` string: Omitted on a shared link.
    - `name` string, required
    - `head` integer, nullable, required: The mob's head count, null until counted.
    - `status` 'under_withholding' | 'clear', required
    - `safe_for_slaughter_on` string, nullable, required: The latest safe-for-slaughter date among the treatments, or null when none is recorded.
    - `export_eligible_on` string, nullable, required
    - `treatments` TreatmentRegisterRow[], required
      - `record_type` 'treatment' | 'husbandry': Whether the record is a treatment given to the mob or husbandry done to it (a product given at marking).
      - `what` string: What it was, in a farmer's words: `Drench`, `Vaccine`, `Lice`, or for husbandry the procedures, e.g. `Marking, Tail docking`.
      - `record_id` string: The drench record. Omitted on a shared link.
      - `task_id` string: The task that is the record. Omitted on a shared link.
      - `mob_id` string: Omitted on a shared link.
      - `treatment_date` string, required
      - `mob` string, required
      - `location` string, required: The paddock the mob was in on the treatment date, or `not recorded`.
      - `head` string, required: Head treated, as a string, or `not recorded`.
      - `product` string, required: Product trade name, or `not recorded`.
      - `batch` string, required
      - `expiry` string, required
      - `dose` string, required
      - `route` string, required
      - `whp_days` string, required: This product's withholding period in days, or `not recorded` (0 days is treated as not entered).
      - `esi_days` string, required
      - `safe_for_slaughter_on` string, required: Treatment date plus the longest WHP among the record's named products, or `not recorded`.
      - `export_eligible_on` string, required: Treatment date plus the longest ESI among the record's named products, or `not recorded`.
      - `treated_by` string, required
      - `under_withholding` boolean, required: Whether either safe date is still ahead of today (the whole record, not just this product).
      - `not_recorded` string[], required
  - `columns` PaddockRegisterColumn[]: Paddock registers only.
    - `key` string: The key of the value in each row.
    - `label` string: The heading to print.
    - `width` integer: A relative width; scale to the space available.
  - `definitions` string: Paddock registers only.
  - `paddocks` PaddockRegisterGroup[]: The spray and paddock inputs registers only.
    - `id` string: Omitted on a shared link.
    - `name` string
    - `area_ha` number, nullable
    - `status` 'clear' | 'under_withholding'
    - `safe_to_graze_on` string, date, nullable
    - `safe_to_harvest_on` string, date, nullable
    - `records` PaddockRegisterRow[]
      - `record_id` string: Omitted on a shared link.
      - `task_id` string: Omitted on a shared link.
      - `paddock_id` string: Omitted on a shared link.
      - `paddock` string
      - `under_withholding` boolean: A spray row whose grazing or harvest date is still ahead today. Always false for paddock inputs.
      - `not_recorded` string[]
  - `rows` union[], required
    - union
      - TreatmentRegisterRow: One PRODUCT of one completed treatment or husbandry record: a row of the LPA Section 2 treatment register. A value the record does not carry is the literal text `not recorded` (never empty), and `not_recorded` lists those keys so a client can set them in amber italic. Dates are ISO 8601 (`YYYY-MM-DD`) or `not recorded`. `expiry` and `route` are what was entered, and `not recorded` where nobody did (a husbandry record has no route).
        - `record_type` 'treatment' | 'husbandry': Whether the record is a treatment given to the mob or husbandry done to it (a product given at marking).
        - `what` string: What it was, in a farmer's words: `Drench`, `Vaccine`, `Lice`, or for husbandry the procedures, e.g. `Marking, Tail docking`.
        - `record_id` string: The drench record. Omitted on a shared link.
        - `task_id` string: The task that is the record. Omitted on a shared link.
        - `mob_id` string: Omitted on a shared link.
        - `treatment_date` string, required
        - `mob` string, required
        - `location` string, required: The paddock the mob was in on the treatment date, or `not recorded`.
        - `head` string, required: Head treated, as a string, or `not recorded`.
        - `product` string, required: Product trade name, or `not recorded`.
        - `batch` string, required
        - `expiry` string, required
        - `dose` string, required
        - `route` string, required
        - `whp_days` string, required: This product's withholding period in days, or `not recorded` (0 days is treated as not entered).
        - `esi_days` string, required
        - `safe_for_slaughter_on` string, required: Treatment date plus the longest WHP among the record's named products, or `not recorded`.
        - `export_eligible_on` string, required: Treatment date plus the longest ESI among the record's named products, or `not recorded`.
        - `treated_by` string, required
        - `under_withholding` boolean, required: Whether either safe date is still ahead of today (the whole record, not just this product).
        - `not_recorded` string[], required
      - PaddockRegisterRow: One PRODUCT line of one completed spray, fertiliser or sowing: a row of a paddock register. The keys are the register's `columns`. A value the record should carry and does not is the literal text `not recorded` (listed in `not_recorded`); a value that is genuinely optional and absent is null (print an em dash). Dates are ISO 8601 (`YYYY-MM-DD`). Spray rows carry `spray_date`, `paddock`, `crop`, `area_ha`, `product`, `batch`, `rate`, `water_rate`, `method`, `applicator`, `done_for`, `weather` and the two end dates `safe_to_graze_on` and `safe_to_harvest_on`. Paddock input rows carry `input_date`, `paddock`, `area_ha`, `operation`, `role`, `product`, `rate`, `total_kg`, `method`, `analysis`, `batch`, `applicator` and `safe_to_graze_on` (a seed treatment only).
        - `record_id` string: Omitted on a shared link.
        - `task_id` string: Omitted on a shared link.
        - `paddock_id` string: Omitted on a shared link.
        - `paddock` string
        - `under_withholding` boolean: A spray row whose grazing or harvest date is still ahead today. Always false for paddock inputs.
        - `not_recorded` string[]

## Other responses

- `403`: An api or MCP bearer token.
- `404`: Not a link.
- `410`: The link has expired or been revoked.
- `429`: Too many requests.

---

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