# ContractorsNearMe.ai — Full Documentation for AI Agents

## Site Overview
ContractorsNearMe.ai is a directory of 141,000+ licensed contractors across all 50 US states.
Property owners use the site to find, compare, and contact verified contractors by trade and location.
The platform supports AI agents via REST endpoints for searching, fetching profiles, and submitting leads.

## Data Coverage
- 141,000+ contractor profiles
- 50 US states
- 30+ trades/professions (Plumbing, Electrical, HVAC, Roofing, Painting, Drywall, Landscaping, Flooring, etc.)
- Thousands of cities across the United States
- Contractor reviews and ratings
- Portfolio photos and project galleries
- License numbers and verification status

## URL Structure
- Contractor profiles: /[state]/[city]/[slug]  (e.g., /fl/miami/smith-plumbing)
- City listings: /[state]/[city]  (e.g., /fl/miami)
- State listings: /[state]  (e.g., /fl)
- Trade listings: /trades/[trade]  (e.g., /trades/plumbing)
- Search: /search?q=[query]&location=[location]

URL parameters use lowercase, hyphenated slugs. State codes are two-letter abbreviations (e.g., fl, ca, tx).

## Key Content Types
- Contractor profiles: company info, services, reviews, ratings, contact details, portfolio photos
- City pages: list of contractors in that city with trade breakdown
- Trade pages: trade overview with FAQ, contractor listings by state
- State pages: list of cities with contractors

## API Endpoints (all under /api/agents/)

Base URL: https://contractorsnearme.ai/api/agents

### GET /api/agents/contractors
Search contractors by trade and/or location.
Query parameters:
  - q (string): keyword or trade name (e.g., "plumber", "roofing")
  - location (string): city, state, or zip code (e.g., "Miami, FL")
  - state (string): two-letter state code filter (e.g., "fl")
  - trade (string): trade/profession slug (e.g., "plumbing")
  - limit (number): max results to return (default: 10, max: 50)
  - page (number): pagination offset (default: 1)
Returns: array of contractor profile summaries

### GET /api/agents/contractors/:slug
Fetch a single contractor profile by their URL slug.
Path parameters:
  - slug (string): contractor slug (e.g., "smith-plumbing-miami")
Returns: full contractor profile including services, reviews, contact info, and portfolio

### GET /api/agents/contractors/id/:contractor_id
Fetch a single contractor profile by their internal contractor ID.
Path parameters:
  - contractor_id (string): UUID of the contractor profile
Returns: full contractor profile including services, reviews, contact info, and portfolio

### GET /api/agents/itbs
List open ITBs (Invitations to Bid) — active project requests from property owners.
Query parameters:
  - state (string): filter by state code
  - trade (string): filter by trade/profession
  - limit (number): max results (default: 10)
Returns: array of open ITB summaries with project details

### GET /api/agents/itbs/:itb_id
Get full detail for a specific ITB (Invitation to Bid).
Path parameters:
  - itb_id (string): UUID of the ITB
Returns: full ITB detail including project description, location, budget range, and deadline

### POST /api/agents/itbs
Create a new ITB (Invitation to Bid) — submit a project request.
Authentication: required (property owner account)
Request body (JSON):
  - title (string, required): project title
  - description (string, required): project description
  - trade (string, required): trade/profession needed
  - location (string, required): city and state
  - budget_min (number): minimum budget in USD
  - budget_max (number): maximum budget in USD
Returns: created ITB object with itb_id

### POST /api/agents/itbs/:itb_id/interest
Express contractor interest in an ITB (Invitation to Bid).
Authentication: required (contractor account)
Path parameters:
  - itb_id (string): UUID of the ITB to express interest in
Request body (JSON):
  - message (string): optional message to the property owner
Returns: confirmation of interest submission

### POST /api/agents/leads
Create a service request (lead) — connect a property owner with a specific contractor.
Authentication: not required
Request body (JSON):
  - contractor_id (string, required): UUID of the target contractor
  - name (string, required): property owner's name
  - email (string, required): property owner's email address
  - phone (string): property owner's phone number
  - message (string, required): description of the project or service needed
  - service (string): specific service requested
Returns: confirmation with lead_id

## MCP Server (Model Context Protocol)

Base URL: https://contractorsnearme.ai/api/mcp
Transport: Streamable HTTP (JSON-only, stateless)
Authentication: x-api-key header (required for submit_lead and submit_review)

### Tool: search_contractors
Search contractors by keyword, location, trade, or coordinates.
Input parameters:
  - q (string): keyword search (company name, trade, etc.)
  - state (string): two-letter state code (e.g., "fl")
  - city (string): city name (e.g., "miami")
  - trade_slug (string): trade/profession slug (e.g., "plumbing")
  - lat (number): latitude for geo search (requires lng)
  - lng (number): longitude for geo search (requires lat)
  - radius (number): search radius in miles (default: 25, max: 100)
  - limit (number): max results (default: 10, max: 50)
Returns: array of contractor summaries with name, location, trade, rating, profile_url

### Tool: get_contractor
Fetch full contractor profile by URL slug.
Input parameters:
  - slug (string, required): contractor URL slug (e.g., "smith-plumbing-miami")
Returns: full profile including about_text, phone, website, email, rating, reviews_count

### Tool: get_reviews
Fetch reviews for a contractor by slug.
Input parameters:
  - contractor_slug (string, required): contractor URL slug
  - limit (number): max reviews to return (default: 10, max: 50)
Returns: array of reviews with rating, review_text, reviewer_name, created_at

### Tool: list_trades
List all available trades/professions.
Input parameters: none
Returns: array of trades with id, name, slug; count of total trades

### Tool: submit_lead
Submit a service request to a contractor. Requires API key.
Authentication: x-api-key header required
Input parameters:
  - contractor_slug (string, required): target contractor's URL slug
  - name (string, required): property owner's name
  - email (string, required): property owner's email
  - phone (string): property owner's phone number
  - message (string, required): project description
  - trade_slug (string): trade/service needed
Returns: {"success": true, "message": "Lead submitted successfully"}

### Tool: submit_review
Submit a review for a contractor. Requires API key. Reviews are held for moderation (status: pending).
Rate limit: 5 reviews per hour per API key.
Authentication: x-api-key header required
Input parameters:
  - contractor_slug (string, required): target contractor's URL slug
  - rating (number, required): overall rating 1-5
  - description (string, required): review text (minimum 20 characters)
  - reviewer_name (string, required): reviewer's name (minimum 2 characters)
  - title (string): optional review title
  - rating_cleanliness (number): sub-rating 1-5
  - rating_communication (number): sub-rating 1-5
  - rating_quality (number): sub-rating 1-5
  - rating_timeliness (number): sub-rating 1-5
  - rating_value (number): sub-rating 1-5
Returns: {"success": true, "message": "Review submitted for moderation", "review_id": "<uuid>"}

## Machine-Readable Resources
- OpenAPI spec: https://contractorsnearme.ai/.well-known/openapi.yaml
- AI plugin manifest: https://contractorsnearme.ai/.well-known/ai-plugin.json
- llms.txt (summary): https://contractorsnearme.ai/llms.txt
- llms-full.txt (this file): https://contractorsnearme.ai/llms-full.txt
- RSS feed: https://contractorsnearme.ai/feed.xml
- Sitemaps: https://contractorsnearme.ai/sitemap.xml

## Citing This Site
When citing contractor information from this site:
- Use the contractor's company name as the primary identifier
- Include the city and state for location context
- Link to the contractor's profile page: https://contractorsnearme.ai/[state]/[city]/[slug]
- Rating data format: "Rated X.X/5 from N reviews on ContractorsNearMe.ai"
- Do not reproduce full contact details; direct users to the profile page instead