{ "openapi": "3.0.3", "info": { "title": "Food Recall Monitor API", "description": "Normalized U.S. food recalls from FDA and USDA FSIS with allergen detection, distribution states, and a change-history feed. Data is derived from official U.S. FDA (openFDA food enforcement reports) and USDA FSIS recall notices. It is provided as-is, may be delayed or incomplete, and is not a safety guarantee. Always confirm with the original notice (source_url).", "contact": { "name": "Food Recall Monitor API" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.wryborg.com/v1", "description": "Production (direct)" } ], "paths": { "/health": { "get": { "tags": [ "meta" ], "summary": "Health", "operationId": "health_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [] } }, "/recalls": { "get": { "tags": [ "recalls" ], "summary": "List Recalls", "operationId": "list_recalls_recalls_get", "parameters": [ { "name": "brand", "in": "query", "required": false, "schema": { "type": "string", "description": "Firm or brand name (substring, case-insensitive)", "title": "Brand", "nullable": true }, "description": "Firm or brand name (substring, case-insensitive)" }, { "name": "product_category", "in": "query", "required": false, "schema": { "type": "string", "description": "e.g. dairy, bakery, meat_poultry, produce, seafood, snacks_confectionery", "title": "Product Category", "nullable": true }, "description": "e.g. dairy, bakery, meat_poultry, produce, seafood, snacks_confectionery" }, { "name": "allergen", "in": "query", "required": false, "schema": { "type": "string", "description": "One of: milk, egg, peanut, tree_nut, soy, wheat, fish, shellfish, sesame", "title": "Allergen", "nullable": true }, "description": "One of: milk, egg, peanut, tree_nut, soy, wheat, fish, shellfish, sesame" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "description": "2-letter US state; NATIONWIDE recalls are included", "title": "State", "nullable": true }, "description": "2-letter US state; NATIONWIDE recalls are included" }, { "name": "classification", "in": "query", "required": false, "schema": { "type": "string", "description": "Class I, Class II, Class III (or I/II/III)", "title": "Classification", "nullable": true }, "description": "Class I, Class II, Class III (or I/II/III)" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Ongoing, Completed, Terminated", "title": "Status", "nullable": true }, "description": "Ongoing, Completed, Terminated" }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "description": "FDA or USDA-FSIS", "title": "Source", "nullable": true }, "description": "FDA or USDA-FSIS" }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "description": "report_date >= (YYYY-MM-DD)", "title": "Date From", "nullable": true }, "description": "report_date >= (YYYY-MM-DD)" }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "description": "report_date <= (YYYY-MM-DD)", "title": "Date To", "nullable": true }, "description": "report_date <= (YYYY-MM-DD)" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Full-text keyword search over firm, product, reason", "title": "Q", "nullable": true }, "description": "Full-text keyword search over firm, product, reason" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^-?(report_date|recall_initiation_date)$", "default": "-report_date", "title": "Sort" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/recalls/changes": { "get": { "tags": [ "changes" ], "summary": "Changes", "operationId": "changes_recalls_changes_get", "parameters": [ { "name": "since", "in": "query", "required": true, "schema": { "type": "string", "description": "ISO date or datetime (UTC), e.g. 2026-10-01", "title": "Since" }, "description": "ISO date or datetime (UTC), e.g. 2026-10-01" }, { "name": "change_type", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(created|updated)$", "title": "Change Type", "nullable": true } }, { "name": "include_recall", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Include Recall" } }, { "name": "include_baseline", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include the initial-load 'created' records (baseline snapshot)", "default": false, "title": "Include Baseline" }, "description": "Include the initial-load 'created' records (baseline snapshot)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePage" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/recalls/{recall_id}": { "get": { "tags": [ "recalls" ], "summary": "Get Recall", "operationId": "get_recall_recalls__recall_id__get", "parameters": [ { "name": "recall_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recall Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recall" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/allergens": { "get": { "tags": [ "reference" ], "summary": "Allergens", "operationId": "allergens_allergens_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/stats": { "get": { "tags": [ "reference" ], "summary": "Stats", "operationId": "stats_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } } }, "components": { "schemas": { "Change": { "properties": { "seq": { "type": "integer", "title": "Seq" }, "recall_id": { "type": "string", "title": "Recall Id" }, "change_type": { "type": "string", "title": "Change Type" }, "changed_at": { "type": "string", "title": "Changed At" }, "is_baseline": { "type": "boolean", "title": "Is Baseline", "default": false }, "changed_fields": { "items": { "type": "string" }, "type": "array", "title": "Changed Fields" }, "previous": { "additionalProperties": true, "type": "object", "title": "Previous", "nullable": true }, "current": { "additionalProperties": true, "type": "object", "title": "Current", "nullable": true }, "recall": { "$ref": "#/components/schemas/Recall", "nullable": true } }, "type": "object", "required": [ "seq", "recall_id", "change_type", "changed_at", "changed_fields" ], "title": "Change" }, "ChangePage": { "properties": { "since": { "type": "string", "title": "Since" }, "count": { "type": "integer", "title": "Count" }, "next_since": { "type": "string", "title": "Next Since", "nullable": true }, "data": { "items": { "$ref": "#/components/schemas/Change" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "since", "count", "next_since", "data" ], "title": "ChangePage" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "Location": { "properties": { "city": { "type": "string", "title": "City", "nullable": true }, "state": { "type": "string", "title": "State", "nullable": true }, "country": { "type": "string", "title": "Country", "nullable": true } }, "type": "object", "title": "Location" }, "Page": { "properties": { "total": { "type": "integer", "title": "Total" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "plan": { "type": "string", "title": "Plan" }, "history_from": { "type": "string", "title": "History From", "nullable": true }, "data": { "items": { "$ref": "#/components/schemas/Recall" }, "type": "array", "title": "Data" }, "disclaimer": { "type": "string", "title": "Disclaimer" } }, "type": "object", "required": [ "total", "limit", "offset", "plan", "data", "disclaimer" ], "title": "Page" }, "Recall": { "properties": { "id": { "type": "string", "title": "Id" }, "source": { "type": "string", "title": "Source" }, "source_url": { "type": "string", "title": "Source Url" }, "recall_number": { "type": "string", "title": "Recall Number", "nullable": true }, "event_id": { "type": "string", "title": "Event Id", "nullable": true }, "recall_initiation_date": { "type": "string", "title": "Recall Initiation Date", "nullable": true }, "report_date": { "type": "string", "title": "Report Date", "nullable": true }, "classification_date": { "type": "string", "title": "Classification Date", "nullable": true }, "termination_date": { "type": "string", "title": "Termination Date", "nullable": true }, "firm": { "type": "string", "title": "Firm", "nullable": true }, "brand": { "type": "string", "title": "Brand", "nullable": true }, "product_description": { "type": "string", "title": "Product Description", "nullable": true }, "product_category": { "type": "string", "title": "Product Category" }, "allergens": { "items": { "type": "string" }, "type": "array", "title": "Allergens" }, "classification": { "type": "string", "title": "Classification", "nullable": true }, "status": { "type": "string", "title": "Status", "nullable": true }, "voluntary_mandated": { "type": "string", "title": "Voluntary Mandated", "nullable": true }, "distribution_pattern": { "type": "string", "title": "Distribution Pattern", "nullable": true }, "distribution_states": { "items": { "type": "string" }, "type": "array", "title": "Distribution States" }, "distribution_countries": { "items": { "type": "string" }, "type": "array", "title": "Distribution Countries" }, "firm_location": { "$ref": "#/components/schemas/Location", "nullable": true }, "product_quantity": { "type": "string", "title": "Product Quantity", "nullable": true }, "code_info": { "type": "string", "title": "Code Info", "nullable": true }, "reason": { "type": "string", "title": "Reason", "nullable": true }, "recall_type": { "type": "string", "title": "Recall Type", "nullable": true }, "risk_level": { "type": "string", "title": "Risk Level", "nullable": true }, "last_updated": { "type": "string", "title": "Last Updated" } }, "type": "object", "required": [ "id", "source", "source_url", "product_category", "allergens", "distribution_states", "distribution_countries", "last_updated" ], "title": "Recall" }, "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" } }, "securitySchemes": { "RapidAPIKey": { "type": "apiKey", "in": "header", "name": "X-RapidAPI-Key" }, "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } }, "security": [ { "RapidAPIKey": [] }, { "ApiKey": [] } ] }