Aristocles Pty Ltd Food Recalls API

openapi: 3.2.0
info:
  title: Aristocles Data Food Recalls API
  description: 'Four Australian data APIs on one key — subscriptions, trade pricing, PBS drugs, and rental prices.


    ---


    ## Quick start


    **1. Get your API key** — register in one request:

    ```

    POST /v1/auth/register

    {"email": "you@example.com", "name": "Your Name"}

    ```

    Copy the `api_key` from the response.


    **2. Authenticate** — add your key to every request as a header:

    ```

    X-API-Key: ar_live_xxxxxxxxxxxx

    ```


    **3. Run the discovery endpoint** — returns all available slugs, example calls, and your account limits:

    ```

    GET /v1/discovery

    ```


    **4. Make your first call:**

    ```

    GET /v1/prices/netflix?country=AU

    GET /v1/trades/electrician/prices?state=NSW&country=AU

    GET /v1/pbs/metformin

    GET /v1/rental/VIC/Richmond

    ```


    ---


    ## Four data domains


    | Domain | Base path | What it covers |

    |---|---|---|

    | **Subscription Pricing** | `/v1/prices`, `/v1/services` | 50+ SaaS & streaming services: Netflix, Spotify, Adobe, etc. |

    | **Contractor Trades** | `/v1/trades` | Plumbers, electricians, painters across AU, US, UK, CA, NZ |

    | **PBS Drug Pricing** | `/v1/pbs` | 14,000+ medications on Australia''s Pharmaceutical Benefits Scheme |

    | **Rental Market** | `/v1/rental` | Median weekly rent by suburb and postcode across Australia |

    | **RBA Economic Data** | `/v1/rba` | Cash rate, AUD FX rates, CPI inflation, mortgage rates, credit aggregates |


    ---


    ## MCP Server


    All four data domains are also available as MCP tools at:

    ```

    https://api.aristocles.com.au/mcp/

    ```

    Connect any MCP-compatible AI agent (Claude, GPT, Gemini) to get structured data without writing API calls.'
  version: 2.1.0
tags:
- name: Food Recalls
  description: 'Food recall and enforcement records covering the recalled product, the reason for the recall, the hazard classification, distribution area, and the firm and dates involved. Records are business and product level, not consumer level. Bought by grocery, food-service and supply-chain platforms that must catch an affected product before it reaches a shelf or a menu. Source: Data courtesy of openFDA, U.S. Food and Drug Administration. Not endorsed by the FDA.. Licence: Public domain (U.S. Government work), openFDA terms of service. Base path: /v1/data/united-states-food-recalls. Requires an API key (X-API-Key).'
paths:
  /v1/data/united-states-food-recalls:
    get:
      tags:
      - Food Recalls
      summary: List United States Food Recalls records
      description: 'List United States Food Recalls records with optional filters and pagination.


        **Source:** Data courtesy of openFDA, U.S. Food and Drug Administration. Not endorsed by the FDA. (Public domain (U.S. Government work), openFDA terms of service).


        **Fields returned:**

        - `recall_number` (str) — Unique recall identifier

        - `event_id` (str) — Identifier grouping related recall records

        - `status` (str) — Ongoing, completed, terminated or pending

        - `classification` (str) — Hazard class, where Class I is the most serious

        - `product_type` (str) — Product category, typically Food

        - `product_description` (str) — Description of the recalled product

        - `reason_for_recall` (str) — Why the product was recalled, such as an undeclared allergen

        - `recalling_firm` (str) — Company conducting the recall

        - `city` (str) — City of the recalling firm

        - `state` (str) — State or territory of the recalling firm

        - `country` (str) — Country of the recalling firm

        - `distribution_pattern` (str) — Where the product was distributed

        - `product_quantity` (str) — Amount of product affected as reported

        - `code_info` (str) — Lot codes, batch numbers or use-by dates identifying affected stock

        - `voluntary_mandated` (str) — Whether the recall was voluntary or ordered

        - `initial_firm_notification` (str) — How the firm first notified its customers

        - `recall_initiation_date` (date) — Date the firm began the recall

        - `report_date` (date) — Date the recall was published

        - `termination_date` (date) — Date the recall was closed out


        **Example:** `GET /v1/data/united-states-food-recalls?limit=10&classification=example`'
      operationId: list_endpoint_v1_data_united_states_food_recalls_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Max records to return (1-100).
          default: 25
          title: Limit
        description: Max records to return (1-100).
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Records to skip, for pagination.
          default: 0
          title: Offset
        description: Records to skip, for pagination.
      - name: classification
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Hazard class, where Class I is the most serious
          examples:
          - example
          title: Classification
        description: Hazard class, where Class I is the most serious
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Ongoing, completed, terminated or pending
          examples:
          - example
          title: Status
        description: Ongoing, completed, terminated or pending
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: State or territory of the recalling firm
          examples:
          - example
          title: State
        description: State or territory of the recalling firm
      - name: country
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Country of the recalling firm
          examples:
          - example
          title: Country
        description: Country of the recalling firm
      - name: recalling_firm
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Company conducting the recall
          examples:
          - example
          title: Recalling Firm
        description: Company conducting the recall
      - name: product_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Product category, typically Food
          examples:
          - example
          title: Product Type
        description: Product category, typically Food
      - name: report_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Date the recall was published
          examples:
          - '2026-01-01'
          title: Report Date
        description: Date the recall was published
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: A page of United States Food Recalls records with pagination metadata.
          content:
            application/json:
              schema: {}
              example:
                data:
                  items:
                  - recall_number: example
                    event_id: example
                    status: example
                    classification: example
                    product_type: example
                    product_description: example
                    reason_for_recall: example
                    recalling_firm: example
                    city: example
                    state: example
                    country: example
                    distribution_pattern: example
                    product_quantity: example
                    code_info: example
                    voluntary_mandated: example
                    initial_firm_notification: example
                    recall_initiation_date: '2026-01-01'
                    report_date: '2026-01-01'
                    termination_date: '2026-01-01'
                  total: 1
                  limit: 25
                  offset: 0
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/data/united-states-food-recalls/search:
    get:
      tags:
      - Food Recalls
      summary: Search United States Food Recalls by product_description
      description: 'Search United States Food Recalls records by `product_description` (partial, case-insensitive).


        **Example:** `GET /v1/data/united-states-food-recalls/search?q=exa`'
      operationId: search_endpoint_v1_data_united_states_food_recalls_search_get
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 100
          description: Case-insensitive partial match on product_description.
          examples:
          - exa
          title: Q
        description: Case-insensitive partial match on product_description.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Max records to return (1-100).
          default: 25
          title: Limit
        description: Max records to return (1-100).
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: Matching United States Food Recalls records.
          content:
            application/json:
              schema: {}
              example:
                data:
                  items:
                  - recall_number: example
                    event_id: example
                    status: example
                    classification: example
                    product_type: example
                    product_description: example
                    reason_for_recall: example
                    recalling_firm: example
                    city: example
                    state: example
                    country: example
                    distribution_pattern: example
                    product_quantity: example
                    code_info: example
                    voluntary_mandated: example
                    initial_firm_notification: example
                    recall_initiation_date: '2026-01-01'
                    report_date: '2026-01-01'
                    termination_date: '2026-01-01'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/data/united-states-food-recalls/{key}:
    get:
      tags:
      - Food Recalls
      summary: Get one United States Food Recalls record by recall_number
      description: 'Fetch a single United States Food Recalls record by its `recall_number`.


        **Example:** `GET /v1/data/united-states-food-recalls/example`'
      operationId: get_endpoint_v1_data_united_states_food_recalls__key__get
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
          description: The recall_number value to look up (case-insensitive).
          examples:
          - example
          title: Key
        description: The recall_number value to look up (case-insensitive).
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: A single United States Food Recalls record.
          content:
            application/json:
              schema: {}
              example:
                data:
                  recall_number: example
                  event_id: example
                  status: example
                  classification: example
                  product_type: example
                  product_description: example
                  reason_for_recall: example
                  recalling_firm: example
                  city: example
                  state: example
                  country: example
                  distribution_pattern: example
                  product_quantity: example
                  code_info: example
                  voluntary_mandated: example
                  initial_firm_notification: example
                  recall_initiation_date: '2026-01-01'
                  report_date: '2026-01-01'
                  termination_date: '2026-01-01'
        '404':
          content:
            application/json:
              example:
                error:
                  code: NOT_FOUND
                  message: No United States Food Recalls record for '...'.
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError