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

# Health Inspections

> Look up the health inspections of a New York City food service establishment: scores, grades and violations, newest first.

Given a New York City establishment id (CAMIS) or part of a trade name, return the matching food service establishments with their health inspections from the New York City Department of Health and Mental Hygiene: name, address, borough, ZIP code, cuisine and location, then for each inspection its date, type, score, letter grade with its date, the action taken and the violations cited, each with its code, description and whether it is critical. Give at least one of `establishment_id` and `name`; the id takes precedence when both are given. `name` matches anywhere in the trade name, ignoring case; `zipcode` narrows either search. Inspections are newest first, at most `limit` per establishment. The call reads the 200 newest violation rows that match, so a name shared by many establishments may leave out older inspections: add `zipcode` or use the id; when those rows all fall on one date the call fails as invalid input for the same reason. An establishment not yet inspected has an empty `inspections` list. Dates are YYYY-MM-DD and a value the source does not give is null. No match is a completed result with an empty `establishments` list.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

<ParamField body="establishment_id" type="string">
  The city's establishment id (CAMIS), for example 40732665; takes precedence over name. establishment\_id must be digits.
</ParamField>

<ParamField body="name" type="string">
  Part of the trade name, matched anywhere in it and ignoring case, for example Katz's Delicatessen. 2 to 100 characters.
</ParamField>

<ParamField body="zipcode" type="string">
  Five-digit ZIP code of the establishment. zipcode must be five digits.
</ParamField>

<ParamField body="limit" type="integer">
  Most inspections to return per establishment. From 1 to 20. Defaults to `5`.
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

<ResponseField name="data.request_id" type="string">
  Durable job ID for audit and lookup
</ResponseField>

<ResponseField name="data.status" type="string">
  Job status: `completed`
</ResponseField>

<ResponseField name="data.tool" type="string">
  Always `business_health_inspections`
</ResponseField>

<ResponseField name="data.result" type="object">
  The answer, described under Result below
</ResponseField>

<ResponseField name="data.evidence" type="object">
  Where the answer came from and when
</ResponseField>

<ResponseField name="data.evidence.source" type="string">
  The public body the data comes from. Always `New York City Department of Health and Mental Hygiene`.
</ResponseField>

<ResponseField name="data.evidence.source_kind" type="string">
  `public` when the data comes from a public body, `commercial` otherwise
</ResponseField>

<ResponseField name="data.evidence.retrieved_at" type="string">
  When the lookup was made, as an ISO 8601 UTC time
</ResponseField>

<ResponseField name="data.evidence.as_of" type="string">
  The newest date the city ran its daily extract (`record_date`, YYYY-MM-DD) among the rows read, or `null` when no row matched
</ResponseField>

## Result

Nested under `data.result`.

<ResponseField name="data.result.establishments" type="object[]">
  The matching establishments, the most recently inspected first, then those not inspected yet; empty when none matches.
</ResponseField>

<ResponseField name="data.result.establishments[].establishment_id" type="string">
  The city's establishment id (CAMIS).
</ResponseField>

<ResponseField name="data.result.establishments[].name" type="string">
  The trade name. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.establishments[].address" type="string">
  Building number and street. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.establishments[].borough" type="string">
  The borough, for example Manhattan. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.establishments[].zipcode" type="string">
  Five-digit ZIP code. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.establishments[].cuisine" type="string">
  The cuisine the city records, for example Sandwiches. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.establishments[].latitude" type="number">
  Latitude, or null when the city could not place the address.
</ResponseField>

<ResponseField name="data.result.establishments[].longitude" type="number">
  Longitude, or null when the city could not place the address.
</ResponseField>

<ResponseField name="data.result.establishments[].inspections" type="object[]">
  Inspections, newest first (same-day inspections by type), at most `limit`; empty when the establishment has not been inspected yet.
</ResponseField>

<ResponseField name="data.result.establishments[].inspections[].date" type="string">
  Date of the inspection, YYYY-MM-DD.
</ResponseField>

<ResponseField name="data.result.establishments[].inspections[].type" type="string">
  Program and kind of inspection, for example Cycle Inspection / Initial Inspection. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.establishments[].inspections[].score" type="number">
  Points for the violations found (lower is better), or null when the inspection was not scored.
</ResponseField>

<ResponseField name="data.result.establishments[].inspections[].grade" type="string">
  Letter grade given at this inspection: A, B or C; N not yet graded; Z grade pending; P grade pending on reopening after a closure. Null when none was given. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.establishments[].inspections[].grade_date" type="string">
  Date of the grade, YYYY-MM-DD, or null.
</ResponseField>

<ResponseField name="data.result.establishments[].inspections[].action" type="string">
  What the city did at the inspection, in its words. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.establishments[].inspections[].violations" type="object[]">
  The violations cited, by code; empty when none was recorded.
</ResponseField>

<ResponseField name="data.result.establishments[].inspections[].violations[].code" type="string">
  The violation code the city uses, for example 04N.
</ResponseField>

<ResponseField name="data.result.establishments[].inspections[].violations[].description" type="string">
  What the inspector cited, in the city's words. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.establishments[].inspections[].violations[].critical" type="boolean">
  Whether the city flags the violation as critical.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/lookup/business-health-inspections \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "establishment_id": "40732665",
      "limit": 3
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/business-health-inspections", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      "establishment_id": "40732665",
      "limit": 3
    }),
  });
  ```

  ```typescript SDK theme={null}
  const result = await agent.tool('lookup/business-health-inspections', {
    establishment_id: '40732665',
    limit: 3
  });
  console.log(result.data.result);
  console.log(result.data.evidence);
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "success": true,
    "data": {
      "request_id": "uuid",
      "receipt_id": "rcpt_...",
      "status": "completed",
      "tool": "business_health_inspections",
      "result": {
        "establishments": [
          {
            "establishment_id": "40732665",
            "name": "KATZ'S DELICATESSEN",
            "address": "205 EAST HOUSTON STREET",
            "borough": "Manhattan",
            "zipcode": "10002",
            "cuisine": "Sandwiches",
            "latitude": 40.72250411745,
            "longitude": -73.987300961167,
            "inspections": [
              {
                "date": "2026-09-30",
                "type": "Inter-Agency Task Force / Initial Inspection",
                "score": 0,
                "grade": null,
                "grade_date": null,
                "action": "No violations were recorded at the time of this inspection.",
                "violations": []
              },
              {
                "date": "2026-07-13",
                "type": "Administrative Miscellaneous / Initial Inspection",
                "score": null,
                "grade": null,
                "grade_date": null,
                "action": "No violations were recorded at the time of this inspection.",
                "violations": []
              },
              {
                "date": "2026-07-13",
                "type": "Cycle Inspection / Initial Inspection",
                "score": 20,
                "grade": null,
                "grade_date": null,
                "action": "Violations were cited in the following area(s).",
                "violations": [
                  {
                    "code": "04H",
                    "description": "Raw, cooked or prepared food is adulterated, contaminated, cross-contaminated, or not discarded in accordance with HACCP plan.",
                    "critical": true
                  },
                  {
                    "code": "04K",
                    "description": "Evidence of rats or live rats in establishment's food or non-food areas.",
                    "critical": true
                  },
                  {
                    "code": "04N",
                    "description": "Filth flies or food/refuse/sewage associated with (FRSA) flies or other nuisance pests in establishment’s food and/or non-food areas. FRSA flies include house flies, blow flies, bottle flies, flesh flies, drain flies, Phorid flies and fruit flies.",
                    "critical": true
                  },
                  {
                    "code": "08A",
                    "description": "Establishment is not free of harborage or conditions conducive to rodents, insects or other pests.",
                    "critical": false
                  },
                  {
                    "code": "10B",
                    "description": "Anti-siphonage or back-flow prevention device not provided where required; equipment or floor not properly drained; sewage disposal system in disrepair or not functioning properly. Condensation or liquid waste improperly disposed of.",
                    "critical": false
                  },
                  {
                    "code": "10F",
                    "description": "Non-food contact surface or equipment made of unacceptable material, not kept clean, or not properly sealed, raised, spaced or movable to allow accessibility for cleaning on all sides, above and underneath the unit.",
                    "critical": false
                  },
                  {
                    "code": "28-05",
                    "description": "Food adulterated or misbranded. Adulterated or misbranded food possessed, being manufactured, produced, packed, sold, offered for sale, delivered or given away",
                    "critical": false
                  }
                ]
              }
            ]
          }
        ]
      },
      "evidence": {
        "source": "New York City Department of Health and Mental Hygiene",
        "source_kind": "public",
        "retrieved_at": "2026-10-18T04:44:00.000Z",
        "calls": [
          {
            "retrieved_at": "2026-10-18T04:44:00.000Z"
          }
        ],
        "as_of": "2026-10-16"
      }
    }
  }
  ```
</ResponseExample>

<Info>See [Pricing](/pricing) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.</Info>

## Notes

* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.