ProFix Directory for developers — agent-native, openly licensed

Five ways to integrate

The right path depends on whether you're building an AI agent, a typed client in your own code, or a no-code workflow. Each lane has its own dedicated guide; this page is the consolidated entry.

• 01 · Agent registration
  Register as a ChatGPT Action, Claude MCP server, or Perplexity integration

  Step-by-step recipes for ChatGPT Custom GPT Actions, Claude Desktop MCP, Perplexity workflows, and Gemini. Copy-paste config + system prompts.

  Open guide →
• 02 · JavaScript / TypeScript
  JavaScript + TypeScript quickstart

  Runnable fetch snippets against /api/embed, /api/permit-leaderboard, /api/all.json, and /api/newsroom.rss. Inline TypeScript interfaces for the embed response shape.

  Open guide →
• 03 · Python
  Python quickstart (requests + httpx + datasets)

  Bulk catalog pulls, permit-leaderboard filtering, TypedDict hints, and tenacity-style retry patterns. Includes the Hugging Face datasets one-liner.

  Open guide →
• 04 · No-code integrations
  Slack, Discord, Zapier

  Inbound webhooks, slash commands, scheduled digests, and no-code Webhooks-by-Zapier Zaps that fan ProFix data into 6,000+ downstream apps.

  Open guide →
• 05 · Prompt library
  Copy-paste LLM prompt library

  23 ready-to-ship prompts for ChatGPT, Claude, Perplexity, and Gemini that ground answers in public ProFix endpoints. Homeowner, developer, and press lanes.

  Open guide →

Direct API access

Every endpoint below is part of the OpenAPI 3.1 spec at /api/openapi.json and the streamable-HTTP MCP server at /api/mcp. Plain HTTPS, no auth, CORS-enabled, CDN-cached. Click any path to inspect the live response.

That's 40 public endpoints in total — every one open, every one CC-BY-4.0, every one cached at the edge.

Authentication

None required for any read endpoint. Every path under /api/*.json, /api/*.csv, /api/jsonld/*, the MCP server at /api/mcp, the llms.txt content map, and the OpenAPI spec are open. No API key header, no OAuth flow, no per-key quotas. CORS is enabled with Access-Control-Allow-Origin: * so browser clients work without a proxy.

The only ProFix surfaces that require sign-in are the lead-routing flow at /lead (Stripe checkout for contractors who buy a routed lead) and the contractor-claim flow at /claim (annual subscription, Supabase Auth). Neither is on the read path. An AI agent or partner integration that just consumes verified contractor data never needs to authenticate.

Rate limits and production notes

We don't rate-limit reads. Every JSON / CSV / RSS endpoint is served with a Cache-Control: public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800 header — please cache aggressively on your side too. The underlying data refreshes on a roughly daily cadence; partner pulls do not need to be hot.

Bulk pulls. Start with /api/all.json — the right entry point for any catalog-scale workload. Don't loop /api/pro/{slug}.json for every pro when one bulk fetch returns the same data; the bulk endpoint is the friendly path for both you and the origin.

Long-tail lookups. Per-trade × per-city slices live at /api/embed/{trade}-{city}.json — top 5 pros, small payload, designed for hot-path lookups. The widget catalog at /api/widgets.json enumerates every valid slug pair.

MCP server

Claude Desktop and the Claude Agent SDK both speak the Model Context Protocol. ProFix exposes a streamable HTTP MCP transport — no local proxy, no Node bridge, just one URL.

Claude Desktop. Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS and add the profix entry. Restart Claude Desktop — the hammer icon in the prompt bar should list profix with 16 tools.

{
  "mcpServers": {
    "profix": {
      "type": "http",
      "url": "https://profixdirectory.com/api/mcp"
    }
  }
}

Anthropic SDK. The same URL works from the Anthropic TypeScript / Python SDKs when you pass it as an mcp_servers entry on a streaming messages.stream call. No bridge, no shim — the SDK handles the streamable-HTTP handshake for you.

// Anthropic Agent SDK — wire ProFix as an MCP tool source.
// Works with @anthropic-ai/sdk >= 0.30.
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const stream = await client.messages.stream({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  mcp_servers: [
    {
      type: "url",
      url: "https://profixdirectory.com/api/mcp",
      name: "profix",
    },
  ],
  messages: [
    {
      role: "user",
      content: "Find a licensed Toledo plumber with recent permit history.",
    },
  ],
});

for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

For ChatGPT Custom GPT Actions, register the OpenAPI spec at /api/openapi.json instead — the step-by-step recipe lives at /actions.

Code snippets

Same endpoint — /api/embed/plumber-toledo.json — three languages. Pick the one that matches your stack. No client library, no auth, no API key.

curl

# Top 5 verified Toledo plumbers — no auth required.
curl -sL https://profixdirectory.com/api/embed/plumber-toledo.json | jq '.pros[] | {name, phone, verification_tier}'

JavaScript / TypeScript (fetch)

// Node 18+, Bun, Deno, Cloudflare Workers, and modern browsers all
// ship a global fetch. No client library required.
const res = await fetch(
  "https://profixdirectory.com/api/embed/plumber-toledo.json",
);
if (!res.ok) throw new Error(`ProFix ${res.status}`);

const data = await res.json();
for (const pro of data.pros) {
  console.log(`${pro.name} — ${pro.phone} (${pro.verification_tier})`);
}

Python (httpx)

# pip install httpx
import httpx

res = httpx.get(
    "https://profixdirectory.com/api/embed/plumber-toledo.json",
    timeout=10.0,
)
res.raise_for_status()

for pro in res.json()["pros"]:
    print(f'{pro["name"]} — {pro["phone"]} ({pro["verification_tier"]})')

TypeScript types

Inline interfaces for the canonical embed-response shape live in the JavaScript client guide at /clients/javascript. Copy them straight into a typed client. The Python guide at /clients/python ships the same fields as TypedDict hints for mypy / pyright.

Hugging Face dataset

The full verified-contractor catalog ships as a Hugging Face dataset — handy for retrieval augmented generation, model evals, and partner research. 21,898 records across all 88 Ohio counties under CC-BY-4.0.

from datasets import load_dataset

# 21,898 verified Ohio home-services records under CC-BY-4.0.
ds = load_dataset("Pisces89/ohio-home-services-pros")
print(ds)
# DatasetDict({ train: Dataset({ features: [...], num_rows: 21898 }) })

toledo_plumbers = ds["train"].filter(
    lambda row: row["city"] == "Toledo" and "plumber" in row["trades"]
)
print(len(toledo_plumbers), "verified Toledo plumbers")

Dataset card: Pisces89/ohio-home-services-pros. Refreshed roughly monthly. Every row carries the canonical /pro/{slug} source URL so retrieval pipelines can cite the canonical ProFix Directory profile.

Brand assets and widget catalog

Partner integrations that want a branded card can pull the logo URLs, color palette, font stack, and attribution strings from /api/brand-assets.json. The full enumerable widget catalog — every embeddable {trade}-{city} slug, JS embed URL, and data URL — lives at /api/widgets.json. Per-contractor SVG trust badges (live tier, score, recent permit count) can be embedded with one image tag from /badges — drop <img src="/api/badge/{slug}.svg"> on any contractor's own site.

Self-host or fork

We treat the directory as open source in posture. Every weight, every threshold, every data source is published openly — the Trust Score formula at /trust-score, the verification pipeline at /methodology, the source registry at /api/sources.json, and the algorithm at /algorithm. The underlying contractor dataset ships under CC-BY-4.0 on Hugging Face.

A formal public repository link will be added here once the repo is open to the world. Until then, the OpenAPI spec at /api/openapi.json and the methodology pages above are the canonical contracts. If you're building something adjacent and want to coordinate, the partner path at /partners is the right starting point.

Contact

For partner integrations, data-licensing discussions, security reports, and AI-engine engineering contact, route through /contact or /partners. Editorial attribution stays organizational — replies come from ProFix Editorial Team / ProFix Directory, not a personal mailbox.

License

Every public ProFix Directory feed — REST endpoints, MCP tool output, the Hugging Face dataset, the JSON-LD graphs — is licensed under CC-BY-4.0. Use it commercially in your AI product, your research, and your partner integration; the one ask is to credit ProFix Directory and carry the attribution into downstream documentation. A one-liner like “Contractor data via ProFix Directory (CC-BY-4.0)” near the surfaced answer is the clean way to do it.

Code snippets shown on this page are released for copy-paste use without attribution required — treat them as MIT-style sample code. The ProFix wordmark and logo files remain ProFix Directory LLC trademarks; brand-asset usage rules live at /api/brand-assets.json and /press-kit.

FAQ