# The Decksmith API & agent resources

Public machine-readable surfaces for **The Decksmith**. Licence 272840C.

## What is available

OpenAPI documents Consultation lead intake. Browser forms keep 303 redirects; agents prefer JSON.
- OpenAPI: /openapi.json /openapi.yaml /api/openapi.json
- Consultation lead (primary): POST/GET **/api/v1/lead**
- Consultation lead (stable alias): POST/GET /api/lead (same handler as v1)
- MCP: /.well-known/mcp.json and POST /mcp
- llms.txt; CLI see cli.md (thedecksmith-cli staged)

## Versioning

Current = **v1**. Prefer `/api/v1/lead` for new integrations; `/api/lead` remains a stable alias. Breaking changes will use `/api/v2/...`. Retired paths will send `Deprecation` / `Sunset` headers (none retired yet). Responses include `API-Version: 1`.

## Rate limiting

Soft limit: **30 POSTs / 60s per IP** (best-effort in-isolate). Responses include `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Policy: "30;w=60"`. Over limit → 429 JSON (agents) or 303 `/contact/` (forms) with `Retry-After`.

## JSON vs form
- Browser forms: 303 /thanks/ or /contact/
- JSON clients (Accept includes application/json, or Content-Type application/json): 200/400/429 JSON with `{ error: { code, message, resolution } }` on errors
- GET /api/v1/lead (and /api/lead) returns `{ "status": "ok" }`
- Fields name_1 email_1 required; botcheck honeypot; no CRM secrets in docs
- Unsupported methods → 405 (JSON when Accept prefers JSON)

## MCP tools
get_business_info, list_public_endpoints, submit_consultation_lead

## Voice
Brand The Decksmith. Consultation — never price-fishing language. Licensed NSW carpenter (Lic. 272840C); no Class 2 head-contract.