# Open — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search FDA food recall and enforcement actions to find safety information about specific products or manufacturers, and look up adverse events reported to the CFSAN Adverse Event Reporting System (CAERS). Filter, sort, and aggregate data by various fields to analyze food safety trends and monitor enforcement activity.

**Category:** Government & Public Data | **Website:** [open.fda.gov/](https://open.fda.gov/) | **Docs:** [parse.bot/marketplace/8a4b9935-db6e-45d1-a117-b32e97103362/open-fda-gov-api](https://parse.bot/marketplace/8a4b9935-db6e-45d1-a117-b32e97103362/open-fda-gov-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-open-fda-gov-api-8a4b9935/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### count_food_enforcement_by_field

Count and aggregate food recall enforcement records by a specific field. Returns term-count pairs showing the distribution of values for the given field. Useful for understanding the breakdown of recalls by status, classification, state, or other categorical fields.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `field` | string | Yes | Field name to aggregate by, with '.exact' suffix for exact matching (e.g. 'status.exact', 'classification.exact', 'state.exact', 'voluntary_mandated.exact') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-open-fda-gov-api-8a4b9935/count_food_enforcement_by_field \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"field":"<string>"}'
```

### get_food_adverse_events_by_product

Retrieve food adverse event reports for a specific product by its brand name. Searches the products.name_brand field and returns matching adverse event reports with consumer demographics, reactions, outcomes, and full product details.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product` | string | Yes | Product brand name to search for (e.g. 'CENTRUM SILVER', 'Nature Valley') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-open-fda-gov-api-8a4b9935/get_food_adverse_events_by_product \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product":"<string>"}'
```

### get_food_enforcement_by_recall_number

Retrieve a specific food recall enforcement report by its unique recall number. Returns the matching recall record with full details including status, classification, recalling firm, product description, reason for recall, and distribution information.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `recall_number` | string | Yes | Unique recall number identifier (e.g. 'F-0276-2017', 'H-0659-2026') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-open-fda-gov-api-8a4b9935/get_food_enforcement_by_recall_number \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recall_number":"<string>"}'
```

### get_food_enforcement_by_status

Retrieve food recall enforcement reports filtered by recall status. Returns paginated recall records matching the specified status value. Use skip and limit for pagination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return |
| `skip` | integer | No | Number of results to skip for pagination |
| `status` | string | Yes | Recall status to filter by |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-open-fda-gov-api-8a4b9935/get_food_enforcement_by_status \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","skip":"<integer>","status":"<string>"}'
```

### search_food_adverse_events

Search food adverse event reports from the CFSAN Adverse Event Reporting System (CAERS). Returns reports containing consumer demographics (age, gender), reactions, outcomes, product details (brand name, industry), and dates. Paginates via skip/limit.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return |
| `search` | string | No | Lucene-style search query to filter adverse event results (e.g. 'reactions:"NAUSEA"', 'outcomes:"Death"') |
| `skip` | integer | No | Number of results to skip for pagination |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-open-fda-gov-api-8a4b9935/search_food_adverse_events \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","search":"<string>","skip":"<integer>"}'
```

### search_food_enforcement

Search food recall enforcement reports from the FDA Recall Enterprise System (RES). Supports Lucene-style search queries, sorting, and pagination. Returns recall records including recall_number, product_description, status, classification, recalling_firm, reason_for_recall, and distribution details. Paginates via skip/limit (max skip 25000, max limit 1000).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return (1-1000) |
| `search` | string | No | Lucene-style search query filtering results by any field (e.g. 'status:"Ongoing"', 'classification:"Class I"', 'recalling_firm:"Kraft"') |
| `skip` | integer | No | Number of results to skip for pagination (0-25000) |
| `sort` | string | No | Field and direction to sort by, formatted as 'field_name:direction' where direction is 'asc' or 'desc' (e.g. 'recall_initiation_date:desc') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-open-fda-gov-api-8a4b9935/search_food_enforcement \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","search":"<string>","skip":"<integer>","sort":"<string>"}'
```