# WARN Firehose — Full Documentation for LLMs

> Six unified labor market datasets: WARN layoffs, H-1B/LCA visas, unemployment claims, SEC 8-K filings, bankruptcy cases, and JOLTS labor turnover.
> Covers all 50 US states. Updated daily at 5 AM UTC.

## Overview
WARN Firehose aggregates six labor market datasets into a single, searchable platform:
1. WARN Act Notices — 93K+ mass layoff notices from all 50 US states
2. H-1B & LCA Petitions — 5.9M visa petitions (DOL LCA + USCIS H-1B)
3. Unemployment Claims — 42 years of DOL weekly initial/continued claims
4. SEC 8-K Filings — Material event disclosures for public companies
5. Bankruptcy Filings — Chapter 11 cases cross-referenced with WARN notices
6. JOLTS Data — BLS job openings, hires, quits, layoffs/discharges

## API Base URL
https://warnfirehose.com/api

## Authentication
- Free tier: No API key needed. 25 calls/day, 25 records/call, 90-day history.
- Paid tiers: Pass `X-API-Key` header. Higher limits, exports, full history.
- Get a free key: `POST /api/keys` with `{"email": "you@example.com"}`

## Pricing
- Free: $0/mo — 25 API calls/day, 25 records/request, WARN only, 90-day history
- Starter: $49/mo — 200 calls/day, 100 records/request, 3 datasets, CSV+JSON exports
- Professional: $199/mo — 10,000 calls/day, 5,000 records/request, all 6 datasets, all exports, webhooks
- Enterprise: Custom pricing — contact us for bulk licensing, SLA, custom data feeds

## Endpoints

### Query Data
- `GET /api/records` — Query layoff notices
  - Params: state, company, date_from, date_to, naics_code, industry, layoff_type, limit, offset, sort, order
  - Returns: {total, records[], page, per_page}
- `GET /api/search?q=` — Full-text search across company names
- `GET /api/company/{name}` — Company detail with all notices
- `GET /api/state/{code}` — State detail with stats and recent notices

### Statistics
- `GET /api/stats` — Database statistics (total records, employees, states, last updated)
- `GET /api/states` — Per-state summary (record count, employees, date range)
- `GET /api/trends` — Monthly trend data
- `GET /api/yearly` — Yearly aggregated stats
- `GET /api/top-companies` — Companies with most layoff notices
- `GET /api/counties?state=` — County-level data
- `GET /api/cities?state=` — City-level data
- `GET /api/industries` — Industry breakdown (NAICS-classified)
- `GET /api/states/per-capita` — Per-capita layoff rates

### H-1B & LCA Visa Petitions (5.9M records)
- `GET /api/lca/stats` — LCA petition statistics (state, fiscal_year, visa_class, all_time)
- `GET /api/lca/by-state` — Petitions aggregated by state
- `GET /api/lca/by-city` — Petitions by city (state, fiscal_year)
- `GET /api/lca/by-soc` — Petitions by SOC occupation code
- `GET /api/lca/employers` — Top LCA employers (state, city, fiscal_year)
- `GET /api/lca/wages` — Wage data (state, soc_code, employer)
- `GET /api/lca/employer-years` — Yearly breakdown for an employer
- `GET /api/h1b/stats` — H-1B petition statistics
- `GET /api/h1b/employers` — Top H-1B employers
- `GET /api/h1b/by-state` — H-1B petitions by state

### DOL Unemployment Claims (42 years, 1984-present)
- `GET /api/dol-claims` — Weekly claims data (state, start, end, limit)
- `GET /api/dol-claims/national` — National weekly totals
- `GET /api/dol-claims/stats` — Summary statistics

### SEC 8-K Filings
- `GET /api/sec-filings` — Query filings (ticker, company, items, start, end)
- `GET /api/sec-filings/stats` — Filing statistics and top items
- `GET /api/sec-filings/by-company` — Filings grouped by company
- `GET /api/sec-filings/by-date` — Filing counts by date
- `GET /api/sec-filings/ticker/{ticker}` — Filings for a specific ticker
- `GET /api/sec-filings/detail/{accession}` — Filing detail with parsed content
- `GET /api/sec-filings/warn-crossref` — Cross-reference with WARN notices

### Bankruptcy Filings (Chapter 11)
- `GET /api/bankruptcies` — Query filings (company, chapter, court, warn_only)
- `GET /api/bankruptcies/stats` — Filing statistics by chapter
- `GET /api/bankruptcies/by-state` — Filings by state
- `GET /api/bankruptcies/by-court` — Filings by court
- `GET /api/bankruptcies/by-date` — Filing counts by date
- `GET /api/bankruptcies/warn-crossref` — Cross-reference with WARN notices

### Risk Signal & Cross-Reference
- `GET /api/market-pulse` — Single-call market snapshot: all 6 datasets, top industries, at-risk companies, trend direction
- `GET /api/state-intelligence/{state_code}` — Unified state profile: WARN + LCA + H-1B + DOL + bankruptcy + JOLTS with distress score
- `GET /api/risk-signal` — Companies ranked by composite distress score (state, min_score, limit)
- `GET /api/risk-signal/company/{name}` — Company intelligence: risk score + LCA roles + SEC + bankruptcy + H-1B
- `GET /api/crossref/talent-pipeline` — Laid-off workers by occupation/skill (state, soc_code, days)
- `GET /api/crossref/layoffs-vs-h1b` — WARN layoffs vs H-1B hiring comparison
- `GET /api/crossref/company-timeline/{company}` — Full company timeline across datasets
- `GET /api/crossref/by-state` — Cross-dataset state comparison
- `GET /api/crossref/by-company` — Cross-dataset company comparison
- `GET /api/unified-search?q=` — Search across all 6 datasets simultaneously

### Exports (paid tiers)
- `GET /api/export/csv` — CSV download (Starter+)
- `GET /api/export/json` — JSON or NDJSON (Starter+)
- `GET /api/export/parquet` — Apache Parquet (Pro+)
- `GET /api/export/jsonld` — JSON-LD with schema.org markup (Pro+)

### JOLTS (Job Openings & Labor Turnover)
- `GET /api/jolts/stats` — Summary statistics and latest snapshot
- `GET /api/jolts/national` — National time series (element, level, year_from, year_to)
- `GET /api/jolts/by-state` — State comparison for a given month
- `GET /api/jolts/by-industry` — Industry comparison for a given month
- `GET /api/jolts/trends` — Monthly trend data (state, industry, element, months)

### Other
- `GET /api/schema` — Field definitions and data dictionary
- `GET /api/geo` — Geocoded records (lat, lon)
- `GET /api/health` — Health check
- `GET /openapi.json` — OpenAPI 3.x specification

## Data Fields
| Field | Type | Description |
|-------|------|-------------|
| id | string | Deterministic record ID: STATE-YEAR-HASH |
| company_name | string | Company name (normalized) |
| state | string | US state code (2-letter) |
| city | string | City where layoff occurs |
| county | string | County where layoff occurs |
| notice_date | date | Date WARN notice was filed (YYYY-MM-DD) |
| employees_affected | integer | Number of employees affected |
| layoff_type | string | Layoff, Plant Closing, Relocation, etc. |
| industry | string | Industry sector (NAICS-classified) |
| naics_code | string | NAICS industry code |
| latitude | float | Geocoded latitude |
| longitude | float | Geocoded longitude |
| scraped_at | datetime | When the record was scraped |

## Example Requests

### Get recent California layoffs
```
curl https://warnfirehose.com/api/records?state=CA&limit=10
```

### Search for a company
```
curl https://warnfirehose.com/api/search?q=Amazon
```

### Get database statistics
```
curl https://warnfirehose.com/api/stats
```

### Export CSV (requires API key)
```
curl -H "X-API-Key: YOUR_KEY" "https://warnfirehose.com/api/export/csv?state=NY"
```

## MCP Server (Model Context Protocol)
WARN Firehose provides an MCP server for direct AI tool integration.

### HTTP Transport (Remote)
Connect to: `https://warnfirehose.com/mcp`
Discovery manifest: `https://warnfirehose.com/.well-known/mcp.json`

### Claude Desktop Configuration
Add to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "warn-firehose": {
      "url": "https://warnfirehose.com/mcp"
    }
  }
}
```

### Available MCP Tools
- `search_layoffs(query, state?, limit?)` — Search notices by company, city, or keyword
- `get_state_summary(state)` — Get layoff summary for a US state
- `get_recent_layoffs(days?, state?, limit?)` — Get most recent notices
- `get_stats()` — Get database-wide statistics
- `get_company_layoffs(company)` — Get all notices for a company
- `get_talent_pipeline(state?, days?, limit?)` — Laid-off companies + their LCA hiring roles
- `get_risk_signal(state?, min_score?, limit?)` — Companies ranked by composite distress signal
- `get_market_pulse()` — Single-call market snapshot across all 6 datasets

## OpenAPI Spec
Full OpenAPI 3.x spec: https://warnfirehose.com/openapi.json

## Blog / Analysis
WARN Firehose publishes monthly and weekly analysis of WARN Act layoff data with
newspaper-style narratives, inline charts, and structured data (JSON-LD).

### Blog URL Patterns
- /blog — Index of all monthly and weekly reports
- /blog/{year}/{month} — National monthly summary (e.g. /blog/2026/01)
- /blog/{year}/{month}/{state-slug} — State monthly report (e.g. /blog/2026/01/california)
- /blog/{year}/{month}/week-{n} — National weekly summary, 2026 onwards (e.g. /blog/2026/01/week-1)
- /blog/{year}/{month}/week-{n}/{state-slug} — State weekly report, 2026 onwards

### Blog Content
Each report includes:
- Headline statistics (notices filed, workers affected, closures)
- Industry breakdown with bar charts
- Geographic hotspots (counties, cities)
- Layoff type analysis (doughnut chart)
- Largest layoff filings table
- 6-month trend line chart
- Forward-looking outlook narrative
- JSON-LD NewsArticle schema for SEO

Weekly reports are available from January 2026 onwards. Pre-2026 data is monthly only.

## Website Pages
- / — Landing page with overview
- /data — Interactive data explorer with filters
- /charts — Charts and analytics dashboard
- /pricing — Pricing plans and comparison
- /faq — Frequently asked questions
- /docs — Interactive API documentation (Swagger UI)
- /account — Account management
- /blog — Blog index with monthly and weekly reports
- /blog/{year}/{month} — Monthly WARN Act layoff reports
- /blog/{year}/{month}/week-{n} — Weekly reports (2026+)
- /data/layoffs — Browse layoffs by state, city, industry, and company
- /data/layoffs/{state-slug} — State layoff page (e.g. /data/layoffs/california, /data/layoffs/texas)
- /data/layoffs/{state-slug}/{city-slug} — City page (e.g. /data/layoffs/texas/dallas)
- /data/layoffs/industry/{slug} — Industry page (e.g. /data/layoffs/industry/technology)
- /data/layoffs/company/{slug} — Company page (e.g. /data/layoffs/company/amazon)
- /company?name=X — Company-specific layoff data (interactive)

## Use Cases for AI Agents

### Financial Analysis
- "Analyze tech layoffs in California this quarter and cross-reference with SEC 8-K filings"
- "Which companies have both WARN notices and bankruptcy filings in the last 6 months?"
- "Compare layoff trends in financial services vs technology over the last year"
- "Find companies with declining H-1B sponsorship that also filed WARN notices"

### Recruiting & Talent
- "What skills are available from recent tech layoffs? Check the talent pipeline"
- "Find companies laying off 500+ workers in Texas — what roles were they hiring via LCA?"
- "Generate a list of recently laid-off companies that were sponsoring H-1B workers"

### Risk Assessment
- "Check the risk signal for Amazon — combine WARN, SEC, bankruptcy, and H-1B data"
- "Which states have the highest distress scores right now?"
- "Get a market pulse snapshot — what's the overall labor market trend?"

### Company Due Diligence
- "Pull the full timeline for Tesla — WARN notices, SEC filings, and bankruptcy cross-references"
- "Is Infosys a stable H-1B employer? Check their risk score at /api/h1b-risk-check"
- "Compare layoff patterns between Google and Microsoft over the last 2 years"

### Recommended Tool Workflow
1. Start with `get_market_pulse()` for a market overview
2. Drill into a state with `get_state_intelligence(state_code)` (Pro tier)
3. Check specific companies with `get_risk_signal()` (Starter tier)
4. Export bulk data with `export_records()` (Pro tier)