recalls-batch

When the user wants bulk recall checks (many VINs, a fleet, a CSV, or a spreadsheet):

1. Submit — POST at least one of vins, csv, or csvUrl (max 10,000 unique VINs):

   POST https://api.carsxe.com/v1/recalls-batch/submit?key={CARSXE_API_KEY}&source=codex_plugin
   Content-Type: application/json
   {"vins":["..."],"csv":"...","csvUrl":"...","webhookUrl":"..."}

Include only provided fields. csvUrl must be HTTPS and hosted on an allowed provider (Google Sheets, GCS, S3, Dropbox, Azure Blob, DigitalOcean Spaces, Box). Max file size: 5 MB.

Return batchId, status, totalVins, processedVins, hitCount, and timestamps.

1. Status — poll until completed, partial, or failed (every 30–60 seconds; full processing often takes 30–60 minutes unless all VINs are cached):

   GET https://api.carsxe.com/v1/recalls-batch/status?key={CARSXE_API_KEY}&batchId={BATCH_ID}&source=codex_plugin

Present status (uploading | processing | completed | partial | failed), progress (processedVins / totalVins), hitCount, hitRate, and errorMessage if failed.

1. Results (JSON) once complete:

   GET https://api.carsxe.com/v1/recalls-batch/results?key={CARSXE_API_KEY}&batchId={BATCH_ID}&source=codex_plugin

Present job summary, then each VIN: hasRecalls, recallCount, and recall titles / NHTSA numbers / remedy status. HTTP 409 means the batch is still processing.

1. Download (CSV) if the user wants a file:

   GET https://api.carsxe.com/v1/recalls-batch/download?key={CARSXE_API_KEY}&batchId={BATCH_ID}&source=codex_plugin

This returns text/csv, not JSON.

1. For a single VIN use vehicle-recalls (/v1/recalls). For year/make/model with no VIN use recalls-ymm (/v1/recalls-ymm).
2. If the API key is missing, tell the user to set the CARSXE_API_KEY environment variable (see AGENTS.md).