> ## Documentation Index
> Fetch the complete documentation index at: https://docs.closient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Check Recalls

> Check recalls and safety notices for a product by GTIN, optionally narrowed to a specific batch/lot (AI 10), with severity and source agency.

Surface active recalls, safety notices, and health advisories for a product.
Closient aggregates recalls from FDA (food, drug, device), FSIS (meat/poultry),
CPSC (consumer products), and Health Canada, keyed by GTIN with optional
batch/lot narrowing.

## When to use

* User scans a product and asks "is this safe?"
* Before recommending a product in any other skill (`find-alternative`,
  `plan-shopping-trip`, etc.), do a recall check first.
* Agent monitoring a user's recently-purchased items.
* When the scanned packaging encodes a batch/lot in GS1 AI 10 (a GS1
  Digital Link of the form `/01/{gtin}/10/{batch}`), use the batch-specific
  endpoint so the answer is "is *this lot* under recall?" rather than "are
  any batches of this GTIN recalled?".

## Endpoints

### GTIN-level lookup

```
GET /compliance/api/v1/products/{gtin}/recalls
  ?status=ONGOING|COMPLETED|TERMINATED|UNKNOWN
  &severity=CLASS_I|CLASS_II|CLASS_III
  &source_system=FDA|FSIS|CPSC|HEALTH_CANADA
```

Returns every open recall for the GTIN. Defaults to `status=ONGOING` to
show live notices.

### Batch/lot lookup (AI 10)

```
GET /compliance/api/v1/products/{gtin}/batches/{batch}/recalls
  ?status=ONGOING|COMPLETED|TERMINATED|UNKNOWN
  &severity=CLASS_I|CLASS_II|CLASS_III
  &source_system=FDA|FSIS|CPSC|HEALTH_CANADA
```

Returns only the recalls whose `lot_codes` field matches the supplied
`batch`. Matching is case-insensitive and supports four patterns:

* **Exact**: `batch` equals an entry in `lot_codes` (legacy strings,
  free-text token, or `exacts` array in the structured form).
* **Range**: `lot_codes` includes a numeric or alphanumeric range like
  `"lots 20261001 through 20261015"` (free-text) or
  `{"ranges": [["20261001", "20261015"]]}` (structured). The scanned
  batch must be the same length as the endpoints and fall inside the
  inclusive range.
* **Wildcard**: `lot_codes` includes a trailing-`*` pattern like
  `"LOT-2026-*"` or `{"wildcards": ["LOT-2026-*"]}`. Any batch whose
  case-insensitive prefix matches.
* **All-lots**: a recall with an empty `lot_codes` field did not narrow
  to a subset of batches — every lot is considered affected and the
  recall is always returned.

## Typical consumer scan flow

1. Consumer scans a packaging QR encoding a GS1 Digital Link with
   AI 10:
   ```
   https://id.closient.com/01/00012345678905/10/BATCH-2026-042
   ```
2. Agent extracts `gtin=00012345678905`, `batch=BATCH-2026-042`.
3. Agent calls:
   ```
   GET /compliance/api/v1/products/00012345678905/batches/BATCH-2026-042/recalls
   ```
4. If the response is empty, the specific lot is not under recall.
   Surface that explicitly ("No active recalls for lot BATCH-2026-042")
   rather than silently proceeding.
5. If the response contains recalls, surface them prominently — Class I
   first.

Direct scans of `/01/{gtin}/10/{batch}` in a browser hit the resolver,
which routes the consumer through the recall interstitial when an open
recall affects that specific batch (the same lot-matching logic powers
both surfaces). The API endpoint above is for agents that want the
structured response without the redirect dance.

## Response

Array of recall records. Each has:

* `id` — Closient short-UUID
* `title` — short human description
* `status` — ONGOING / COMPLETED / TERMINATED / UNKNOWN
* `severity` — CLASS\_I (most serious) / CLASS\_II / CLASS\_III
* `source_system` — issuing agency
* `description` — free-text narrative
* `hazard` — what harm exposure could cause
* `remedy` — what consumers should do
* `public_url` — authoritative regulator URL
* `company_name` — recalling firm
* `recall_date` — when the regulator initiated the recall
* `jurisdictions` — ISO 3166-1 alpha-2 country codes
* `created` — when Closient first ingested the record

## Severity at a glance

* **CLASS\_I** — reasonable probability of serious adverse health consequences
  or death. Surface prominently.
* **CLASS\_II** — temporary or medically reversible health effects.
* **CLASS\_III** — unlikely to cause adverse health effects; usually labeling
  violations.

## Empty array

An empty response means no active recall for this GTIN (or, for the
batch endpoint, no recall affecting that specific lot). Always worth
saying explicitly ("No active recalls") rather than silently proceeding.

## Related skills

* `resolve-gtin` — get the product detail to display alongside the recall
* `find-alternative` — if recalled, recommend a substitute