{
 "openapi": "3.1.0",
 "info": {
  "title": "ConsumerSun Recall Data API",
  "version": "1.0.0",
  "description": "U.S. product, food, drug, device and vehicle recalls copied from official CPSC, FDA, NHTSA and FSIS feeds. Every record links to the authoritative agency notice. Read-only and unauthenticated."
 },
 "servers": [
  {
   "url": "https://consumersun.com"
  }
 ],
 "paths": {
  "/data/recalls.json": {
   "get": {
    "operationId": "listRecalls",
    "summary": "List and search recall records, newest first",
    "parameters": [
     {
      "name": "source",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "cpsc",
        "fda",
        "nhtsa",
        "fsis"
       ]
      },
      "description": "Filter to one agency feed."
     },
     {
      "name": "category",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "food",
        "pet",
        "baby",
        "vehicles",
        "home",
        "electronics",
        "health"
       ]
      },
      "description": "Filter to one recall category."
     },
     {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "minLength": 2
      },
      "description": "Brand, model, UPC or product search; scored like the on-site recall search (code matches rank first)."
     },
     {
      "name": "slug",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Return the single record for this recall slug instead of a list; 404 when the slug is unknown."
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 200,
       "default": 50
      }
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 0,
       "default": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "A page of recall records with dataset freshness and feed status.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RecallList"
        }
       }
      }
     }
    }
   }
  },
  "/data/recall-index.json": {
   "get": {
    "operationId": "recallIndex",
    "summary": "The Recall Index: this week's counts by agency and category, units affected, largest and newest records",
    "responses": {
     "200": {
      "description": "Weekly index for the current UTC calendar week (Monday through today), with the same-span comparison against last week.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/data/recalls-latest.json": {
   "get": {
    "operationId": "latestRecalls",
    "summary": "The newest 200 recall records in a compact form",
    "responses": {
     "200": {
      "description": "The newest 200 recalls with agency links and data_as_of.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RecallList"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "RecallList": {
    "type": "object",
    "properties": {
     "publisher": {
      "type": "string"
     },
     "data_as_of": {
      "type": "string",
      "format": "date-time"
     },
     "note": {
      "type": "string"
     },
     "total": {
      "type": "integer"
     },
     "limit": {
      "type": "integer"
     },
     "offset": {
      "type": "integer"
     },
     "next_offset": {
      "type": [
       "integer",
       "null"
      ]
     },
     "recalls": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/RecallRecord"
      }
     }
    }
   },
   "RecallRecord": {
    "type": "object",
    "properties": {
     "agency": {
      "type": "string",
      "description": "Agency short name: CPSC, FDA, NHTSA or FSIS."
     },
     "source": {
      "type": "string",
      "enum": [
       "cpsc",
       "fda",
       "nhtsa",
       "fsis"
      ]
     },
     "recall_id": {
      "type": "string",
      "description": "The agency's own recall number or campaign id."
     },
     "slug": {
      "type": "string"
     },
     "date": {
      "type": "string",
      "format": "date",
      "description": "The day the agency published or reported the recall."
     },
     "title": {
      "type": "string"
     },
     "firm": {
      "type": [
       "string",
       "null"
      ]
     },
     "product": {
      "type": "string"
     },
     "hazard": {
      "type": [
       "string",
       "null"
      ],
      "description": "The hazard, or for FDA records the reason for the recall."
     },
     "remedy": {
      "type": [
       "string",
       "null"
      ],
      "description": "What the consumer gets or should do; null on FDA enforcement records, which publish no consumer instructions."
     },
     "categories": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "sold_at": {
      "type": [
       "string",
       "null"
      ]
     },
     "codes": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Digits-only codes (UPCs, model numbers) extracted for matching."
     },
     "image_url": {
      "type": [
       "string",
       "null"
      ]
     },
     "agency_name": {
      "type": "string"
     },
     "agency_url": {
      "type": "string",
      "format": "uri",
      "description": "The authoritative agency record."
     },
     "url": {
      "type": "string",
      "format": "uri",
      "description": "The canonical ConsumerSun page for this recall."
     },
     "facts": {
      "$ref": "#/components/schemas/RecallFacts"
     }
    }
   },
   "RecallFacts": {
    "type": "object",
    "description": "Typed fields derived from the agency record; null where that agency publishes no such field.",
    "properties": {
     "status": {
      "type": [
       "string",
       "null"
      ]
     },
     "classification": {
      "type": [
       "string",
       "null"
      ],
      "description": "FDA hazard class: Class I, Class II or Class III."
     },
     "classification_class": {
      "type": [
       "integer",
       "null"
      ],
      "enum": [
       1,
       2,
       3,
       null
      ]
     },
     "codes_and_lots": {
      "type": [
       "string",
       "null"
      ]
     },
     "quantity": {
      "type": [
       "string",
       "null"
      ]
     },
     "units": {
      "type": [
       "string",
       "null"
      ]
     },
     "distribution": {
      "type": [
       "string",
       "null"
      ]
     },
     "initiated_date": {
      "type": [
       "string",
       "null"
      ]
     },
     "voluntary_or_mandated": {
      "type": [
       "string",
       "null"
      ]
     },
     "incidents": {
      "type": [
       "string",
       "null"
      ]
     },
     "consumer_contact": {
      "type": [
       "string",
       "null"
      ]
     },
     "company": {
      "type": [
       "string",
       "null"
      ]
     },
     "manufactured_in": {
      "type": [
       "string",
       "null"
      ]
     },
     "description": {
      "type": [
       "string",
       "null"
      ]
     }
    }
   }
  }
 }
}