# Septic-Help.com — Agent instructions

Septic-Help.com connects U.S. homeowners with licensed septic contractors (pumping, repair, inspection, installation). This document is for AI assistants and autonomous agents helping users request **free quotes** without opening the website UI.

## Capabilities

| Capability | Endpoint | Method |
|------------|----------|--------|
| Submit quote request | `https://septic-help.com/api/v1/quotes` | `POST` |
| Search contractors | `https://septic-help.com/api/v1/vendors` | `POST` |
| ZIP code lookup | `https://septic-help.com/api/v1/zip-codes/{zip}` | `GET` |

Machine-readable schemas:

- **WebMCP (browser):** On `https://septic-help.com`, supported browsers expose tools via `navigator.modelContext.registerTool()` (e.g. `submit_septic_quote`, `open_quote_form`, `get_agent_discovery`). See [WebMCP](https://webmachinelearning.github.io/webmcp/).
- **Agent Skills index (RFC v0.2.0):** `GET https://septic-help.com/.well-known/agent-skills/index.json` — lists published skills with `name`, `type`, `description`, `url`, and `digest` (`sha256:…`).
- **MCP Server Card (SEP-1649):** `GET https://septic-help.com/.well-known/mcp/server-card.json` — `serverInfo`, Streamable HTTP `transport.endpoint`, and `capabilities` (tools include `submit_septic_quote`). REST today: `POST /api/v1/quotes`.
- **API catalog (RFC 9727):** `GET https://septic-help.com/.well-known/api-catalog` (`Accept: application/linkset+json`) lists APIs with `service-desc`, `service-doc`, and `status` links.
- **Markdown negotiation:** on quote-conversion paths (`/`, `/quote`, `/services`, `/how-it-works`, `/faq`), send `Accept: text/markdown` for a Markdown variant (`Vary: Accept`).
- `https://septic-help.com/.well-known/quote.json`
- `https://septic-help.com/openapi.json`
- `https://septic-help.com/llms.txt` (site overview + quote section)
- `https://septic-help.com/api/v1/health` (API liveness)

## Workflow for agents

1. **Discover** — Read `/.well-known/quote.json` or this file for field names and allowed values.
2. **Interview** — Ask the user the required questions in natural language (ZIP, service type, urgency, contact info).
3. **Consent** — Before submitting, confirm: *"I'll send your name, email, and ZIP code to Septic-Help.com so local septic contractors can contact you. OK?"*
4. **Submit** — `POST /api/v1/quotes` with `"consent": true` and all required fields. Leave `"website"` empty (honeypot).
5. **Confirm** — Tell the user they should hear back within ~24 hours (same-day for emergencies when matched).

**Dry run (test without submitting):** `POST /api/v1/quotes?dry_run=true` with the same JSON body. Returns `200` with `dry_run: true` and a `preview` of the normalized record. No quote is created.

Human fallback: `https://septic-help.com/quote`

## Required JSON fields

| Field | Description |
|-------|-------------|
| `consent` | Must be `true` after explicit user agreement |
| `zip` | 5-digit U.S. ZIP code |
| `service` | `pump-out`, `emergency`, `alarm`, `wet-area`, `inspection`, `repair`, `install`, `other` |
| `urgency` | `emergency`, `week`, `month`, `flexible` |
| `name`, `email` | Contact information |

Optional: `property_type` (`residential`, `cottage`, `commercial`, `multifamily`), `phone`, `description`, `vendor_slug`, `agent_source` (e.g. `chatgpt`).

**Do not** set `website` — it is a spam honeypot.

## Example request

```http
POST /api/v1/quotes HTTP/1.1
Host: septic-help.com
Content-Type: application/json

{
  "consent": true,
  "zip": "28204",
  "service": "pump-out",
  "property_type": "residential",
  "urgency": "week",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "(704) 555-0100",
  "agent_source": "chatgpt"
}
```

## Using OpenAPI with chat completions

Import `https://septic-help.com/openapi.json` as a tool/action in Custom GPTs, Claude, or other OpenAPI-capable agents. The `submitQuoteRequest` operation maps to `POST /api/v1/quotes`.

## API authentication

If the site operator configures `QUOTE_API_KEY` on the Worker, send:

- `Authorization: Bearer <key>`, or
- `X-Quote-Api-Key: <key>`

When no key is configured, the endpoint accepts validated public submissions (rate limiting is at the edge).

## Privacy

- Septic-Help.com is a **lead-generation directory**, not a contractor.
- Submitted data is used to match and notify contractors; see `https://septic-help.com/privacy`.
- Do not submit without clear user consent.

## Contact

- Homeowners: help@septic-help.com