# NC Wedding Guide — Agent Documentation

> Canonical instructions for finding and contacting North Carolina wedding venues and vendors through NC Wedding Guide.

## Coverage and authority

NC Wedding Guide is an independent directory focused exclusively on North Carolina weddings. It contains nearly 4,000 listings across 13 categories and includes canonical listing pages, locations and service areas, descriptions, pricing bands where known, ratings where available, venue settings, amenities, services, capacity, business websites, social profiles, images, phone numbers, and contact availability.

Base URL: `https://www.ncweddingguide.com`

Supported categories:

- `venues`
- `photographers`
- `videographers`
- `planners`
- `florists`
- `caterers`
- `cakes`
- `djs`
- `bands`
- `bridal`
- `jewelers`
- `photo-booths`
- `decor`

## Recommended agent workflow

1. Search `/api/v1/directory` with the user's category, city, and requirements.
2. Present relevant matches with their canonical `listing_url`; do not imply availability or pricing that is not present in the data.
3. Retrieve `/api/v1/vendors/{category}/{slug}` when complete listing details are needed.
4. Only prepare contact when the user wants to contact a specific business.
5. In WebMCP, open the prefilled inquiry and let the user confirm their email, consent, and final Send action. In backend MCP, use the returned email or `mailto_url`; do not claim the message was sent.

## Directory search

`GET /api/v1/directory`

Query parameters:

- `category`: one supported category slug.
- `city`: North Carolina city or area, matched against listing location and service area.
- `q`: free-text match across name, description, location, services, settings, and amenities.
- `limit`: 1–100, default 25.
- `offset`: zero-based pagination offset.

Example:

```http
GET https://www.ncweddingguide.com/api/v1/directory?category=venues&city=Asheville&q=mountain&limit=10
Accept: application/json
```

Each result includes `category`, `slug`, `name`, `location`, known planning attributes, `listing_url`, and a `contact` object. Use the returned `category` and `slug` as stable identifiers for detail and contact calls.

## Listing detail

`GET /api/v1/vendors/{category}/{slug}`

Example:

```http
GET https://www.ncweddingguide.com/api/v1/vendors/venues/{slug}
Accept: application/json
```

The response is public directory data. A `null` field means the guide does not currently know that value; do not guess it.

## Record contact intent and get the email

`POST /api/v1/inquiries`

Use `event_type: "agent_contact_requested"` and `source: "agent_api"` for an agent call. Optional context improves the prepared inquiry and the future lead record.

```http
POST https://www.ncweddingguide.com/api/v1/inquiries
Content-Type: application/json

{
  "category": "venues",
  "slug": "listing-slug-from-search",
  "event_type": "agent_contact_requested",
  "source": "agent_api",
  "visitor_id": "optional-stable-session-id",
  "context": {
    "event_date": "October 2027",
    "guest_count": 120,
    "wedding_location": "Asheville, NC",
    "message": "We are especially interested in outdoor ceremony options."
  }
}
```

Success returns:

- `tracked`: whether the event was durably recorded.
- `event_id`: internal event identifier when available.
- `contact.email`: the business's public contact email.
- `contact.subject` and `contact.body`: a prepared inquiry.
- `contact.mailto_url`: a ready-to-open email action.
- `delivery.status`: currently always `not_forwarded`.
- `delivery.message`: the required truth about what happened.

Important: a successful response does not mean the vendor received a message. NC Wedding Guide records the action and reveals contact instructions today. The caller must send the email separately.

## Deliver a consented lead

The vendor listing page uses the same endpoint with `action: "send_lead"`. This sends the selected business an NC Wedding Guide-branded email and sets Reply-To to the couple's email. Only submit it after the person has approved the details and explicitly consented to sharing them.

```json
{
  "action": "send_lead",
  "category": "venues",
  "slug": "listing-slug-from-search",
  "source": "webmcp",
  "visitor_id": "optional-stable-session-id",
  "inquiry": {
    "couple_name": "Alex",
    "couple_email": "alex@example.com",
    "event_date": "October 2027",
    "guest_count": 120,
    "wedding_location": "Asheville, NC",
    "message": "We are interested in outdoor ceremony options.",
    "consent_to_share": true,
    "agent_session_id": "optional-agent-session",
    "agent_tool": "prepare_vendor_inquiry",
    "attribution": "direct"
  }
}
```

A successful result includes `delivery.status: "sent"`. Anything else is not a delivered lead.

## MCP

Connect a Streamable HTTP MCP client to:

`https://www.ncweddingguide.com/mcp`

The stateless server exposes six tools:

- `search_nc_wedding_directory`
- `get_nc_wedding_vendor`
- `estimate_nc_venue_cost`
- `build_nc_wedding_budget`
- `lookup_nc_marriage_license`
- `request_vendor_contact`

The contact tool has the same behavior and disclosure requirements as the JSON contact action.

## In-browser WebMCP

Supported AI browsers can discover page-aware tools directly on NC Wedding Guide. The directory
search and listing tools work across the site. Vendor pages can prepare an editable inquiry. The
budget, venue-cost, guest-list, and marriage-license pages expose tools that visibly update the
page. Guest-list data stays in the user's browser. A vendor inquiry is sent only after the user
confirms their email, sharing consent, and the final Send action.

## Machine-readable interface

OpenAPI 3.1: `https://www.ncweddingguide.com/api/v1/openapi.json`

MCP discovery: `https://www.ncweddingguide.com/.well-known/mcp.json`

Sitemap: `https://www.ncweddingguide.com/sitemap.xml`