# Shovels API — Building Permit Search

> Shovels API — Building Permit Search is a paid API for AI agents from stable-shovels.dev, paid per call via x402, $0.5/call, status unknown (last checked 2026-09-15, last successful call 2026-07-13).

Search US building permits by date range, location, and contractor with pay-per-call pricing via x402/USDC

## Facts

- Endpoint: POST https://stable-shovels.dev/api/permits/search
- Price: $0.5/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Last successful call: 2026-07-13
- Success rate: 100% of calls made through Zero
- Rating: 4.0 / 5 from 1 review
- Activations on Zero: 3
- Tags: x402
- Canonical page: https://www.zero.xyz/c/shovels-api-building-permit-search-6bf71641
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_MI20eoIFI4fBGE0bUYkWu

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability shovels-api-building-permit-search-6bf71641 -d '<json body>'
```

Example prompt: Search Shovels for building permits filed in Austin, Texas between January 1 and March 31 of 2024, filtered to permits pulled by roofing contractors.

## When to prefer this

Use this endpoint when you need on-demand, no-subscription access to US building permit data and want to pay only per query. Ideal for agents that need occasional permit lookups without committing to a monthly plan, or for workflows where permit searches are infrequent. Best suited for searches scoped by geography, contractor, and date range.

## Known failure modes

- Payment not included or insufficient USDC — returns HTTP 402 requiring x402 payment
- Invalid or missing search parameters — returns 400 bad request
- No permits found matching the filters — returns empty results set
- Rate limiting or server overload — returns 429 or 503
- Location not covered in Shovels dataset — returns empty or partial results

## How this service works

Pay-per-call access to the Shovels building-permits search API over x402 and MPP. Search US building permits by date, location, and contractor — no accounts, no subscriptions, pay per request.

## Output

Returns a list of matching US building permit records including permit dates, locations, contractor names, permit types, and related metadata for permits matching the specified date, location, and contractor filters.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "size": {
   "type": "integer",
   "maximum": 100,
   "minimum": 1,
   "description": "Records to return per page (1–100, default 50). Determines the price — each record returned costs one credit."
  },
  "cursor": {
   "type": "string",
   "description": "Pagination cursor — pass the `next_cursor` from a prior page."
  },
  "geo_id": {
   "type": "string",
   "minLength": 1,
   "description": "Geographic filter: a state code (e.g. \"CA\"), a ZIP code, or a Shovels geolocation id (resolve one via the city/county/jurisdiction search endpoints)."
  },
  "permit_q": {
   "type": "string",
   "maxLength": 50,
   "description": "Substring search over permit text (max 50 chars)."
  },
  "permit_to": {
   "type": "string",
   "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
   "description": "Return permits that started on or before this date (YYYY-MM-DD)."
  },
  "permit_from": {
   "type": "string",
   "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
   "description": "Return permits that started on or after this date (YYYY-MM-DD)."
  },
  "permit_tags": {
   "type": "array",
   "items": {
    "type": "string"
   },
   "description": "Filter by permit classification tags (e.g. \"solar\", \"roofing\"). Prefix a tag with '-' to exclude it."
  },
  "include_count": {
   "type": "boolean",
   "description": "Include a `total_count` of matching permits (first page only)."
  },
  "permit_status": {
   "type": "array",
   "items": {
    "type": "string"
   },
   "description": "Filter by permit status: one or more of final, in_review, inactive, active."
  },
  "property_type": {
   "type": "array",
   "items": {
    "type": "string"
   },
   "description": "Filter by property type (e.g. \"residential\", \"commercial\")."
  },
  "contractor_name": {
   "type": "string",
   "minLength": 3,
   "description": "Filter by contractor name (min 3 chars)."
  },
  "contractor_license": {
   "type": "string",
   "description": "Filter by contractor license number."
  },
  "permit_min_job_value": {
   "type": "number",
   "minimum": 0,
   "description": "Only return permits with at least this job value (USD)."
  },
  "permit_has_contractor": {
   "type": "boolean",
   "description": "Only return permits that have an associated contractor."
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/shovels-api-building-permit-search-6bf71641/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from stable-shovels.dev](https://www.zero.xyz/host/stable-shovels.dev/llms.txt)