Developer documentation / public sample

Query the public surface.

PegeGrid is a structured-data refinery for AI agents. It turns fragmented public information into validated, provenance-backed, versioned datasets. Recording Studios, Med Spas, Plumbers, HVAC, Roofing, and Electrical have bounded public samples; authenticated REST and MCP provide richer structured access.

Overview

Base URL: https://pegegrid.com. Public sample routes are separate by vertical. Recording Studios exposes its Miami sample; Med Spas and Plumbers expose Miami-Dade samples. Plumber public search supports service, emergency_service, availability_24_7, and commercial filters. Available fields vary by record.

Search returns at most 5 records per page and 2 pages per query (10 reachable results). Page stride stays fixed at 5 even with a smaller limit. There is no cursor, free-text search, geographic radius search, full view, or changes feed on the public surface.

Responses include dataset release and freshness metadata. Studio metadata: /v1/sample/meta. Med Spa metadata: /v1/sample/med-spas/meta. Plumber metadata: /v1/sample/plumbers/meta. Roofing metadata: /v1/sample/roofing/meta.

Public REST

GET /v1/sample/entities
GET /v1/sample/entities/{id}
GET /v1/sample/meta

Search filters: city, service, room_type, equipment_category, has_pricing, has_rooms, has_website, and max_hourly_rate. Use limit (1–5) and page (1–2). Filters inspect public facts only, so a zero-result search does not prove a studio lacks that feature.

Plumbers — Miami-Dade

GET /v1/sample/plumbers
GET /v1/sample/plumbers/{id}
GET /v1/sample/plumbers/meta

Plumber search filters: service (normalized category), emergency_service, availability_24_7, and commercial. Set limit to 1–5 and page to 1–2; at most 10 results are reachable per query. Page 3 requires authenticated access. Public records omit protected contacts, street addresses, source URLs, field provenance, and license identifiers/status. Metadata returns the active release and supported public filters.

Search by city

curl -sS 'https://pegegrid.com/v1/sample/entities?city=Miami&limit=5'

Search public services or pricing

curl -sS 'https://pegegrid.com/v1/sample/entities?service=mixing'
curl -sS 'https://pegegrid.com/v1/sample/entities?has_pricing=true'

Fetch a record and metadata

curl -sS 'https://pegegrid.com/v1/sample/entities/{id}'
curl -sS 'https://pegegrid.com/v1/sample/meta'

Replace {id} with an entity_id from a search response. A record outside the sample returns 404. The search response includes data and pagination metadata; the metadata endpoint includes the current release, freshness, sample population, and facets.

HVAC public sample

GET /v1/sample/hvac
GET /v1/sample/hvac/{id}
GET /v1/sample/hvac/meta

Search filters: normalized service, emergency_service, residential, commercial, has_published_pricing, financing, and maintenance_plan. Results are capped at 5 per page and 2 pages. The public sample omits phone, email, street address, website, license identifiers, source URLs, and field provenance.

Public MCP

POST /mcp/public

The endpoint accepts stateless JSON-RPC over HTTP. Send initialize, then tools/list to discover tools. No bearer key is required.

curl -sS 'https://pegegrid.com/mcp/public' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Available tools

  • sample_studios — search the bounded public sample with the REST filters above.
  • sample_studio — retrieve one public record by entity_id.
  • public_dataset_info — inspect Recording Studios release metadata and facets.
  • sample_med_spas, sample_med_spa, public_med_spa_dataset_info — query the bounded Med Spa sample.
  • sample_plumbers — search with service, emergency_service, availability_24_7, and commercial filters; at most 5 results per page and 2 pages.
  • sample_plumber — retrieve one record in the public Plumber sample.
  • public_plumber_dataset_info — inspect release, public-safe coverage, filters, and page bounds.
  • sample_hvac_contractors, sample_hvac_contractor, public_hvac_dataset_info — query the bounded HVAC sample.
  • sample_roofing_contractors, sample_roofing_contractor, public_roofing_dataset_info — query the bounded Roofing sample.
  • sample_electrical_contractors, sample_electrical_contractor, public_electrical_dataset_info — query the bounded Electrical sample.
curl -sS 'https://pegegrid.com/mcp/public' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"sample_studios","arguments":{"city":"Miami","limit":5}}}'

MCP tool results contain a structured JSON response. A request outside the public boundary returns a tool result with isError: true and an authenticated_access_required body.

Med Spa public sample

GET /v1/sample/med-spas
GET /v1/sample/med-spas/{id}
GET /v1/sample/med-spas/meta

Filters: normalized service and has_pricing=true only. A missing price remains unknown. The Med Spa public surface supports no other filters, bulk access, or unrestricted pagination. Responses include names, normalized services, supported structured pricing, release version, and observation date; private contacts, raw source content, and field-level provenance are withheld. Results are capped at 5 per page and 2 pages.

Example

curl -sS 'https://pegegrid.com/v1/sample/med-spas?service=dermal_filler&limit=5'

Roofing public sample

GET /v1/sample/roofing
GET /v1/sample/roofing/{id}
GET /v1/sample/roofing/meta

Filters: service, roof_material, residential, commercial, and emergency_service. At most 5 results per page and 2 pages. The sample contains policy-cleared first-party facts and omits contacts, street addresses, websites, license details, source URLs, and field provenance.

Electrical public sample

GET /v1/sample/electrical
GET /v1/sample/electrical/{id}
GET /v1/sample/electrical/meta

Filters: normalized service, residential, commercial, emergency_service, panel_upgrade, ev_charger, and generator. At most 5 results per page and 2 pages. The sample contains only fields whose first-party source policy is allow_confirmed and omits contact details, license data, source URLs, and field provenance.

Authenticated access

Electrical Contractors — Miami-Dade provides authenticated GET /v1/electrical, GET /v1/electrical/{id}, GET /v1/electrical/meta, and GET /v1/electrical/changes, plus MCP tools search_electrical_contractors, get_electrical_contractor, electrical_dataset_info, and recent_electrical_changes. Search filters include license-record city, license type/status, normalized service, customer type, emergency and 24/7 availability, maintenance plans, and evidenced service/commercial signals. The maintenance-plan filter currently matches 3 records. License geography is not verified physical location or service area; current license is not proof of active commercial operation.

HVAC Contractors — Miami-Dade provides authenticated GET /v1/hvac, GET /v1/hvac/{id}, GET /v1/hvac/meta, and GET /v1/hvac/changes, plus MCP tools search_hvac_contractors, get_hvac_contractor, hvac_dataset_info, and recent_hvac_changes. Filters include physical city, licensee_city, license type/class/status, normalized service, residential/commercial, emergency service, published pricing, financing, and maintenance plan where evidence exists. License status is not operating status. The public HVAC sample is bounded to 5 results per page and 2 pages; it publishes only fields with allow_confirmed first-party provenance.

Roofing Contractors — Miami-Dade provides authenticated GET /v1/roofing, GET /v1/roofing/{id}, GET /v1/roofing/meta, and GET /v1/roofing/changes, plus MCP tools search_roofing_contractors, get_roofing_contractor, roofing_dataset_info, and recent_roofing_changes. Search filters include license-record city, license type/status, normalized service and roof material, residential/commercial work, emergency service, 24/7 availability, and financing where evidenced. License-record geography is separate from verified physical location and service area; license status is separate from operating status.

Authenticated access requires Authorization: Bearer <key>. Authenticated Plumber REST provides GET /v1/plumbers, GET /v1/plumbers/{id}, GET /v1/plumbers/meta, and GET /v1/plumbers/changes. Recording Studios provides GET /v1/entities, GET /v1/entities/{id}, GET /v1/changes, GET /v1/meta, and POST /mcp. Med Spas provides GET /v1/med-spas, GET /v1/med-spas/{id}, GET /v1/med-spas/meta, and Med Spa tools through POST /mcp. The authenticated MCP tools are search_studios, get_studio, dataset_info, search_med_spas, get_med_spa, med_spa_dataset_info, search_plumbers, get_plumber, plumber_dataset_info, and recent_plumber_changes. Plumber search supports city, service, emergency_service, availability_24_7, residential, commercial, has_published_pricing, financing, tankless_water_heater, and hydro_jetting, with limit up to 100 and cursor pagination. Plumber metadata includes active release, dataset version, observed-at range, freshness counts, and filter facets. Capabilities and query fields vary by vertical.

Public routes are bounded, unauthenticated policy projections; authenticated REST and MCP provide broader access with a bearer key. Protected public fields remain withheld, and private R2 is not a public interface. Requests for capabilities outside the public sample return HTTP 401 with authenticated_access_required and a stable capability name. This documentation does not imply that keys are self-service or that a paid plan exists.

Machine-readable docs

OpenAPI JSON describes public REST routes and authenticated Plumber, HVAC, Roofing, and Electrical REST surfaces. Authenticated Studio and Med Spa REST details and all MCP tool definitions are listed here. llms.txt summarizes public interfaces, limits, and the Plumber authenticated surface.