Aristocles Pty Ltd Product Recalls API

openapi: 3.2.0
info:
  title: Aristocles Data Product 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: Product Recalls
  description: 'A catalogue of consumer product recalls published by the U.S. Consumer Product Safety Commission, covering toys, appliances, furniture, electronics, tools and other household goods. Each record includes the recall number, date, title, hazard description and a link to the official recall notice. Marketplaces, retailers, insurers and supply-chain agents use it to pull unsafe products from listings and warn customers. Source: Source: U.S. Consumer Product Safety Commission (CPSC), SaferProducts.gov Recalls API.. Licence: Public Domain (U.S. Government work, 17 U.S.C. 105). Base path: /v1/data/united-states-consumer-product-recalls. Requires an API key (X-API-Key).'
paths:
  /v1/data/united-states-consumer-product-recalls:
    get:
      tags:
      - Product Recalls
      summary: List United States Consumer Product Recalls records
      description: 'List United States Consumer Product Recalls records with optional filters and pagination.


        **Source:** Source: U.S. Consumer Product Safety Commission (CPSC), SaferProducts.gov Recalls API. (Public Domain (U.S. Government work, 17 U.S.C. 105)).


        **Fields returned:**

        - `recall_id` (int) — Internal CPSC recall identifier

        - `recall_number` (str) — Published CPSC recall number

        - `recall_date` (date) — Date the recall was announced

        - `title` (str) — Short recall headline, usually the product and the reason

        - `description` (str) — Description of the recalled product and the hazard

        - `consumer_contact` (str) — How consumers should contact the firm about the recall

        - `last_publish_date` (date) — Date the recall record was last updated

        - `recall_url` (str) — Link to the official CPSC recall notice


        **Example:** `GET /v1/data/united-states-consumer-product-recalls?limit=10&recall_date=2026-01-01`'
      operationId: list_endpoint_v1_data_united_states_consumer_product_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: recall_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Date the recall was announced
          examples:
          - '2026-01-01'
          title: Recall Date
        description: Date the recall was announced
      - name: last_publish_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Date the recall record was last updated
          examples:
          - '2026-01-01'
          title: Last Publish Date
        description: Date the recall record was last updated
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: A page of United States Consumer Product Recalls records with pagination metadata.
          content:
            application/json:
              schema: {}
              example:
                data:
                  items:
                  - recall_id: 42
                    recall_number: example
                    recall_date: '2026-01-01'
                    title: example
                    description: example
                    consumer_contact: example
                    last_publish_date: '2026-01-01'
                    recall_url: example
                  total: 1
                  limit: 25
                  offset: 0
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/data/united-states-consumer-product-recalls/search:
    get:
      tags:
      - Product Recalls
      summary: Search United States Consumer Product Recalls by title
      description: 'Search United States Consumer Product Recalls records by `title` (partial, case-insensitive).


        **Example:** `GET /v1/data/united-states-consumer-product-recalls/search?q=exa`'
      operationId: search_endpoint_v1_data_united_states_consumer_product_recalls_search_get
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 100
          description: Case-insensitive partial match on title.
          examples:
          - exa
          title: Q
        description: Case-insensitive partial match on title.
      - 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 Consumer Product Recalls records.
          content:
            application/json:
              schema: {}
              example:
                data:
                  items:
                  - recall_id: 42
                    recall_number: example
                    recall_date: '2026-01-01'
                    title: example
                    description: example
                    consumer_contact: example
                    last_publish_date: '2026-01-01'
                    recall_url: example
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/data/united-states-consumer-product-recalls/{key}:
    get:
      tags:
      - Product Recalls
      summary: Get one United States Consumer Product Recalls record by recall_number
      description: 'Fetch a single United States Consumer Product Recalls record by its `recall_number`.


        **Example:** `GET /v1/data/united-states-consumer-product-recalls/example`'
      operationId: get_endpoint_v1_data_united_states_consumer_product_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 Consumer Product Recalls record.
          content:
            application/json:
              schema: {}
              example:
                data:
                  recall_id: 42
                  recall_number: example
                  recall_date: '2026-01-01'
                  title: example
                  description: example
                  consumer_contact: example
                  last_publish_date: '2026-01-01'
                  recall_url: example
        '404':
          content:
            application/json:
              example:
                error:
                  code: NOT_FOUND
                  message: No United States Consumer Product 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