# SepticHelp.ca - Agent instructions

SepticHelp.ca connects Canadian homeowners with 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://septichelp.ca/api/v1/quotes` | `POST` |

Machine-readable schemas:

- **WebMCP (browser):** On `https://septichelp.ca`, supported browsers expose tools via `navigator.modelContext.registerTool()` (e.g. `submit_septic_quote`, `find_contractors`, `get_agent_discovery`). See [WebMCP](https://webmachinelearning.github.io/webmcp/).
- **Agent Skills index (RFC v0.2.0):** `GET https://septichelp.ca/.well-known/agent-skills/index.json` — lists published skills with `name`, `type`, `description`, `url`, and `digest` (`sha256:…`).
- **MCP Server Card (SEP-1649):** `GET https://septichelp.ca/.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://septichelp.ca/.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`, `/near-me`, key `/services/*` pages), send `Accept: text/markdown` for a Markdown variant (`Vary: Accept`).
- `https://septichelp.ca/.well-known/quote.json`
- `https://septichelp.ca/openapi.json`
- `https://septichelp.ca/llms.txt` (site overview + quote section)

## 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 (issue, system, access, urgency, contact, property location).
3. **Consent** - Before submitting, confirm: *"I'll send your name, phone, email, and property address to SepticHelp.ca 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).

Human fallback: `https://septichelp.ca/quote`

## Required JSON fields

| Field | Description |
|-------|-------------|
| `consent` | Must be `true` after explicit user agreement |
| `issue_type` | `pumpout`, `backup`, `alarm`, `wetarea`, `inspection`, `replace`, `repair`, `other` |
| `system_type` | `gravity`, `pump`, `advanced`, `unknown` |
| `tank_access` | `easy`, `buried`, `deck`, `unknown` |
| `urgency` | `emergency`, `soon`, `week`, `flexible` |
| `name`, `email`, `phone` | Contact information |
| `address`, `city`, `province` | Property location (Canada) |

Optional: `last_pumped`, `occupants`, `constraints` (array), `postal_code`, `details`, `vendor_slug` (from `/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: septichelp.ca
Content-Type: application/json

{
  "consent": true,
  "issue_type": "pumpout",
  "system_type": "gravity",
  "tank_access": "easy",
  "urgency": "week",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "(403) 555-0100",
  "address": "123 Rural Road",
  "city": "Red Deer",
  "province": "Alberta",
  "agent_source": "chatgpt"
}
```

## 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

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

## Contact

- Homeowners: help@septichelp.ca
- Partners: partners@septichelp.ca