# SavePropTax

> SavePropTax (saveproptax.com) is a California Proposition 8 decline-in-value
> property tax filing service. If a home was worth less on January 1 than its
> assessed value, the county must tax the lower value on request. We check a
> property for free against recent comparable sales, and for a flat $29 we
> prepare and file the county's own review form. The check can only ever lower
> a tax bill, never raise it.

AI agents can call SavePropTax directly. The check endpoint is keyless and free.
The owner always completes the filing themselves: the signing link is emailed to
the owner, never returned to the calling agent, and the owner personally signs
and pays before anything reaches a county.

## Check a property (keyless)

POST https://saveproptax.com/api/agent/check
Body: { "address": "123 Main St, Walnut Creek", "unit": "optional" }

curl -s https://saveproptax.com/api/agent/check \
  -H 'Content-Type: application/json' \
  -d '{"address": "123 Main St, Walnut Creek"}'

Response: { status, message, property: {address, county}, estimate?:
{assessment, opinion, estimatedAnnualSavings}, filing?: {feeUsd, deadline,
reopens?}, continueToken?, cached, checkedAt }

status is one of: qualifies | fair_assessment | not_enough_data |
not_residential | window_closed | county_not_served | already_filed |
address_not_found | needs_more_info | busy. Every message is a relayable
one-sentence explanation. continueToken appears only on qualifies and is valid
24 hours.

## The flow

1. check -> status "qualifies" with a continueToken
2. POST /api/agent/prepare { continueToken, ownerName, ownerPhone, ownerEmail }
   -> we prepare the county form and EMAIL THE SIGNING LINK TO THE OWNER
   -> response is { docId, status: "awaiting_signature", statusUrl,
      ownerEmailSent } and never contains the signing link
3. The owner signs, pays the flat $29, and we file with the County Assessor
4. GET /api/agent/status?doc=<docId> -> awaiting_signature | awaiting_payment |
   filed | delivered | unknown (coarse only, no personal information)

Optional: POST /api/agent/register { agentName, contactEmail } returns an
instant key for the x-agent-key header (higher fresh-check limits, named
attribution). Anonymous use works without it.

## Honesty states

We report fair_assessment when comparable sales do not support a lower value,
and not_enough_data when the evidence is too thin for a defensible filing;
qualifying requires estimated savings above $500 a year and an open county
window. Results are cached 24 hours per address (cached: true). Under heavy
load fresh checks may answer busy while cached answers still serve. Checked
comparables are free to use: an owner can always file directly with their
county at no charge.

## Counties

Pilot counties (windows and deadlines at https://saveproptax.com/counties.html):
Alameda, Contra Costa, Los Angeles, Marin, Napa, Placer, Riverside, Sacramento,
San Benito, San Bernardino, San Francisco, San Joaquin, San Mateo, Santa Clara,
Santa Cruz, Solano, Sutter, Yolo. Windows are seasonal per county; closed
windows return window_closed with the reopen date.

## More

- Human-readable API reference: https://saveproptax.com/agents
- OpenAPI spec: https://saveproptax.com/openapi.json
- MCP server (streamable HTTP, no auth, add by URL): https://saveproptax.com/mcp
  Tools: check_property_tax_savings, start_filing, get_filing_status
- MCP descriptor: https://saveproptax.com/.well-known/mcp.json (the
  .well-known convention for MCP is still a proposal, not a ratified standard;
  the descriptor is published at the path crawlers currently probe)
- API catalog (RFC 9727 linkset): https://saveproptax.com/.well-known/api-catalog
- Support: support@saveproptax.com