{"version":1,"resources":["https://stable-shovels.dev/api/permits/search","https://stable-shovels.dev/api/contractors/search","https://stable-shovels.dev/api/contractors/permits","https://stable-shovels.dev/api/decisions/search","https://stable-shovels.dev/api/addresses/search","https://stable-shovels.dev/api/cities/search","https://stable-shovels.dev/api/counties/search","https://stable-shovels.dev/api/jurisdictions/search","https://stable-shovels.dev/api/states/search","https://stable-shovels.dev/api/zipcodes/search","https://stable-shovels.dev/api/tags"],"description":"Pay-per-call access to the Shovels building-permits search API. Search US building permits by date, location, and rich permit/property/contractor filters. No accounts, no subscriptions — pay per request with x402 or MPP.","instructions":"# Shovels API Reference\n## Authentication\n\nAll endpoints require micropayment. Include payment headers as per the HTTP 402 specification. Payments are processed on Base mainnet (eip155:8453) or Tempo (MPP).\n\n## Base URL\n\nhttps://stable-shovels.dev\n\nAll endpoints are relative to this base URL.\n\n## Agent Workflow (Progressive)\n\n1. Discover candidate endpoints with `mcp__agentcash__discover_api_endpoints(\"https://stable-shovels.dev\")`.\n2. If discovery reports `guidanceAvailable=true` but guidance is omitted, only re-run with `include_guidance=true` when domain-level methodology is needed.\n3. For selected POST endpoints, call `mcp__agentcash__check_endpoint_schema` before first fetch.\n4. Execute with `mcp__agentcash__fetch`.\n\n**AgentCash response envelope:** Paid 200s from `mcp__agentcash__fetch` return `{ success: true, data: <HTTP body> }` — not the bare OpenAPI body. Parse list results at `.data.items` and pagination at `.data.next_cursor`.\n\nIf no endpoint matches the user task, stop this origin flow and switch to another origin.\n\n## Schema Discovery\n\nAll endpoints support schema discovery via the `check_endpoint_schema` tool. Use it on the selected endpoint to confirm request schema and pricing before execution.\n\n---\n\n# Wrapper vs Shovels Upstream Docs\n\nThis service wraps [Shovels API v2](https://docs.shovels.ai/api-reference). The upstream API uses `GET https://api.shovels.ai/v2/...` with query parameters. **stable-shovels.dev does not expose those paths.**\n\n- All search routes here are **POST `/api/*`** with a **JSON body**.\n- Field names match Shovels v2 query param names, but values go in the **body**, not the URL.\n- **Do not** call `GET /v2/permits`, `GET /v2/contractors`, or any `/v2/*` path on stable-shovels.dev — they return 404.\n\n**Wrong field names** (not accepted — observed in prod 404 traffic): `date_start`, `date_end`, `limit`, `permit_type`, `work_type`.\n\n**Correct names:** `permit_from`, `permit_to`, `size` (not `limit`), `permit_tags` (not `permit_type` / `work_type`).\n\n---\n\n# Permit Search Workflow\n\n1. **Geo:** Permit and contractor search require `geo_id`. A state code (`\"TX\"`) or ZIP (`\"75040\"`) works directly. For a city/county/jurisdiction name, resolve first via `POST /api/cities/search`, `/api/counties/search`, or `/api/jurisdictions/search` with `{ \"q\": \"<name>\" }` and take `geo_id` from the result.\n2. **Tags (optional):** `POST /api/tags` lists valid `permit_tags` values (e.g. `hvac`, `solar`, `roofing`).\n3. **Search:** `POST /api/permits/search` with `permit_from`, `permit_to`, `geo_id`, plus optional filters.\n4. **Paginate:** Pass `next_cursor` from the response back as `cursor` on the next request.\n\n---\n\n## POST /api/permits/search\nSearch US building permits by date range and location, with optional permit, property, and contractor filters.\nPrice: $0.005 per record returned (default `size: 50` → $0.25; max `size: 100` → $0.50).\n\n**Required:** `permit_from`, `permit_to` (YYYY-MM-DD), `geo_id`.\n\nExample (HVAC permits in ZIP 75040, 2012–2018, 10 results):\n```json\n{\n  \"permit_from\": \"2012-01-01\",\n  \"permit_to\": \"2018-12-31\",\n  \"geo_id\": \"75040\",\n  \"permit_tags\": [\"hvac\"],\n  \"size\": 10\n}\n```\n\nWRONG — route does not exist on this host:\n```\nGET /v2/permits?geo_id=75040&date_start=2012-01-01&date_end=2018-12-31&limit=10&permit_type=hvac\n```\n\nWRONG — field names and HTTP method:\n```json\n{\n  \"date_start\": \"2012-01-01\",\n  \"date_end\": \"2018-12-31\",\n  \"limit\": 10,\n  \"permit_type\": \"hvac\"\n}\n```\n\n---\n\n## POST /api/contractors/search\nFind contractors active in a location and date range.\nPrice: $0.005 per record (same `size`-based pricing).\n\n**Required:** `permit_from`, `permit_to`, `geo_id`.\n\nExample:\n```json\n{\n  \"permit_from\": \"2024-01-01\",\n  \"permit_to\": \"2024-12-31\",\n  \"geo_id\": \"CA\",\n  \"permit_tags\": [\"solar\"],\n  \"size\": 25\n}\n```\n\n---\n\n## POST /api/contractors/permits\nList every permit linked to one contractor.\nPrice: $0.005 per record.\n\n**Required:** `contractor_id` in the JSON body (maps to upstream path `/contractors/{id}/permits`).\n\nExample:\n```json\n{\n  \"contractor_id\": \"abc123\",\n  \"size\": 50\n}\n```\n\n---\n\n## POST /api/decisions/search\nSearch zoning and land-use decisions by date range and location.\nPrice: $0.005 per record.\n\n**Required:** `decision_from`, `decision_to`, `geo_id`.\n\n**Note:** ZIP codes are **not** supported for `geo_id` on decisions — use a state code or resolve a city/county/jurisdiction id.\n\nExample:\n```json\n{\n  \"decision_from\": \"2023-01-01\",\n  \"decision_to\": \"2023-12-31\",\n  \"geo_id\": \"CA\",\n  \"size\": 25\n}\n```\n\n---\n\n## POST /api/addresses/search\nFind US addresses that have at least one associated permit.\nPrice: $0.005 per record.\n\nExample:\n```json\n{\n  \"q\": \"123 Main St Austin\",\n  \"size\": 10\n}\n```\n\n---\n\n## POST /api/cities/search\nResolve a city name to a `geo_id` for permit/contractor/decision search.\nPrice: $0.005 per record.\n\nExample:\n```json\n{\n  \"q\": \"Austin\",\n  \"size\": 5\n}\n```\n\n---\n\n## POST /api/counties/search\nResolve a county name to a `geo_id`.\nPrice: $0.005 per record. Same body shape as cities search (`{ \"q\": string }`).\n\n---\n\n## POST /api/jurisdictions/search\nResolve a jurisdiction name to a `geo_id`.\nPrice: $0.005 per record. Same body shape as cities search.\n\n---\n\n## POST /api/states/search\nResolve a state name to a `geo_id`.\nPrice: $0.005 per record. Same body shape as cities search.\n\n---\n\n## POST /api/zipcodes/search\nResolve a ZIP code to a `geo_id`.\nPrice: $0.005 per record. Same body shape as cities search.\n\n---\n\n## POST /api/tags\nList available permit classification tags for use in `permit_tags` filters.\nPrice: $0.005 per record.\n\nExample:\n```json\n{\n  \"size\": 50\n}\n```\n\n---\n\n## GET /api/health\nLiveness probe. Free — no payment required.\n\n---\n\n# Common Features\n\n## Pagination\nAll list endpoints are cursor-paginated. Pass the `next_cursor` from a response back as `cursor` on the next request. Control page size with `size` (1–100, default 50).\n\n## Pricing\nOne Shovels credit per record returned, at $0.005/credit. Price is computed from requested `size` before the 402 challenge. `GET /api/health` and `GET /openapi.json` are free.\n\n| Requested size | Price |\n|----------------|-------|\n| 5 (geo lookup) | $0.025 |\n| 50 (default)   | $0.25  |\n| 100 (max)      | $0.50  |\n"}