# Shovels API Reference
## Authentication

All endpoints require micropayment. Include payment headers as per the HTTP 402 specification. Payments are processed on Base mainnet (eip155:8453) or Tempo (MPP).

## Base URL

https://stable-shovels.dev

All endpoints are relative to this base URL.

## Agent Workflow (Progressive)

1. Discover candidate endpoints with `mcp__agentcash__discover_api_endpoints("https://stable-shovels.dev")`.
2. If discovery reports `guidanceAvailable=true` but guidance is omitted, only re-run with `include_guidance=true` when domain-level methodology is needed.
3. For selected POST endpoints, call `mcp__agentcash__check_endpoint_schema` before first fetch.
4. Execute with `mcp__agentcash__fetch`.

**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`.

If no endpoint matches the user task, stop this origin flow and switch to another origin.

## Schema Discovery

All endpoints support schema discovery via the `check_endpoint_schema` tool. Use it on the selected endpoint to confirm request schema and pricing before execution.

---

# Wrapper vs Shovels Upstream Docs

This 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.**

- All search routes here are **POST `/api/*`** with a **JSON body**.
- Field names match Shovels v2 query param names, but values go in the **body**, not the URL.
- **Do not** call `GET /v2/permits`, `GET /v2/contractors`, or any `/v2/*` path on stable-shovels.dev — they return 404.

**Wrong field names** (not accepted — observed in prod 404 traffic): `date_start`, `date_end`, `limit`, `permit_type`, `work_type`.

**Correct names:** `permit_from`, `permit_to`, `size` (not `limit`), `permit_tags` (not `permit_type` / `work_type`).

---

# Permit Search Workflow

1. **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.
2. **Tags (optional):** `POST /api/tags` lists valid `permit_tags` values (e.g. `hvac`, `solar`, `roofing`).
3. **Search:** `POST /api/permits/search` with `permit_from`, `permit_to`, `geo_id`, plus optional filters.
4. **Paginate:** Pass `next_cursor` from the response back as `cursor` on the next request.

---

## POST /api/permits/search
Search US building permits by date range and location, with optional permit, property, and contractor filters.
Price: $0.005 per record returned (default `size: 50` → $0.25; max `size: 100` → $0.50).

**Required:** `permit_from`, `permit_to` (YYYY-MM-DD), `geo_id`.

Example (HVAC permits in ZIP 75040, 2012–2018, 10 results):
```json
{
  "permit_from": "2012-01-01",
  "permit_to": "2018-12-31",
  "geo_id": "75040",
  "permit_tags": ["hvac"],
  "size": 10
}
```

WRONG — route does not exist on this host:
```
GET /v2/permits?geo_id=75040&date_start=2012-01-01&date_end=2018-12-31&limit=10&permit_type=hvac
```

WRONG — field names and HTTP method:
```json
{
  "date_start": "2012-01-01",
  "date_end": "2018-12-31",
  "limit": 10,
  "permit_type": "hvac"
}
```

---

## POST /api/contractors/search
Find contractors active in a location and date range.
Price: $0.005 per record (same `size`-based pricing).

**Required:** `permit_from`, `permit_to`, `geo_id`.

Example:
```json
{
  "permit_from": "2024-01-01",
  "permit_to": "2024-12-31",
  "geo_id": "CA",
  "permit_tags": ["solar"],
  "size": 25
}
```

---

## POST /api/contractors/permits
List every permit linked to one contractor.
Price: $0.005 per record.

**Required:** `contractor_id` in the JSON body (maps to upstream path `/contractors/{id}/permits`).

Example:
```json
{
  "contractor_id": "abc123",
  "size": 50
}
```

---

## POST /api/decisions/search
Search zoning and land-use decisions by date range and location.
Price: $0.005 per record.

**Required:** `decision_from`, `decision_to`, `geo_id`.

**Note:** ZIP codes are **not** supported for `geo_id` on decisions — use a state code or resolve a city/county/jurisdiction id.

Example:
```json
{
  "decision_from": "2023-01-01",
  "decision_to": "2023-12-31",
  "geo_id": "CA",
  "size": 25
}
```

---

## POST /api/addresses/search
Find US addresses that have at least one associated permit.
Price: $0.005 per record.

Example:
```json
{
  "q": "123 Main St Austin",
  "size": 10
}
```

---

## POST /api/cities/search
Resolve a city name to a `geo_id` for permit/contractor/decision search.
Price: $0.005 per record.

Example:
```json
{
  "q": "Austin",
  "size": 5
}
```

---

## POST /api/counties/search
Resolve a county name to a `geo_id`.
Price: $0.005 per record. Same body shape as cities search (`{ "q": string }`).

---

## POST /api/jurisdictions/search
Resolve a jurisdiction name to a `geo_id`.
Price: $0.005 per record. Same body shape as cities search.

---

## POST /api/states/search
Resolve a state name to a `geo_id`.
Price: $0.005 per record. Same body shape as cities search.

---

## POST /api/zipcodes/search
Resolve a ZIP code to a `geo_id`.
Price: $0.005 per record. Same body shape as cities search.

---

## POST /api/tags
List available permit classification tags for use in `permit_tags` filters.
Price: $0.005 per record.

Example:
```json
{
  "size": 50
}
```

---

## GET /api/health
Liveness probe. Free — no payment required.

---

# Common Features

## Pagination
All 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).

## Pricing
One 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.

| Requested size | Price |
|----------------|-------|
| 5 (geo lookup) | $0.025 |
| 50 (default)   | $0.25  |
| 100 (max)      | $0.50  |