Directory - ezForge AI

The Directory API exposes the public listing of businesses that have opted into the Ready directory. List and detail reads are public (no authentication required). Opting in or out requires a session-authenticated request from the business owner. Each listing includes a verificationLevel field indicating the business’s current verification tier. See Business Verification for the full tier system. Rate limits:

Operation	Tier	Limit
`GET /v1/directory`	`directory`	6000 req/min per IP (IPv6 per /64)
`GET /v1/directory/:id`	`directory`	6000 req/min per IP (IPv6 per /64)
`PATCH /v1/directory/:id`	User plan tier	Plan default

Requests with a valid Hub API key are limited per key (and per account) at 300 req/min instead of per IP. Requests whose client IP cannot be determined share a strict 30 req/min bucket. Non-429 GET responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (ISO-8601 timestamp) for the bucket with the least headroom; a 429 adds Retry-After. A 503 carries no rate-limit headers. Caching and freshness: GET /v1/directory and GET /v1/directory/:id are served through a short-lived server-side read cache (30 seconds). Responses are always JSON in the same shape; the cache only affects how quickly a change becomes visible.

Rate limits still apply. The rate-limit check runs before the cache, so a cache hit consumes quota exactly like a database read.
Listing changes show up immediately. The cache is invalidated when a listing’s visibility changes (PATCH /v1/directory/:id), when a business profile or listing categories change (profile edits, Google Business Profile sync, JSON imports, profile-version reverts, onboarding), and when a verification tier is upgraded.
Some fields can lag by up to 30 seconds. Changes to the mcpServerUrl of the listing’s server, to relevanceScore (driven by analytics events), and the initial unverified verification row are not invalidated and appear once the 30-second window expires.
Multi-instance deployments. If the shared cache backend is not configured, invalidation reaches only the instance that performed the write. If the shared backend is unavailable when a write is made, invalidation may not take effect on any instance, including the writer. In either case stale data can be served for up to 30 seconds.
Cache failures are invisible to callers. If the cache backend errors, the request is answered from the database; it never produces a 5xx on its own.

Successful (2xx) GET responses also carry Cache-Control: private, max-age=30 and Vary: Authorization, Accept-Encoding, so a client may reuse a response for up to 30 seconds (including its X-RateLimit-* values). Non-2xx GET responses carry Cache-Control: no-store. A listing hidden via PATCH can therefore remain visible in a client-side cache for up to 30 seconds.

List directory

GET /v1/directory

Returns a paginated list of active Ready-powered business listings. No authentication required. Query parameters:

Parameter	Type	Default	Description
`limit`	integer	20	Max items to return (1–100)
`cursor`	string	—	Opaque cursor from previous response
`search`	string	—	Fuzzy search against listing name
`category`	string	—	Exact category match (listing must include this value)
`location`	string	—	Partial match against city or state
`templateType`	string	—	Exact match against business industry/template type
`vertical`	string	—	Alias for `templateType` (e.g. `salon`, `home-services`)
`city`	string	—	Exact city match (case-insensitive)
`lat`	number	—	Latitude for geolocation search (requires `lng` and `radius_miles`)
`lng`	number	—	Longitude for geolocation search (requires `lat` and `radius_miles`)
`radius_miles`	number	—	Radius in miles for geolocation search
`min_verification`	string	—	Minimum verification level: `phone_verified`, `business_verified`, or `premium_verified`

Response 200:

{
  "data": [
    {
      "id": "01J9Z3K2M4N5P6Q7R8S9T0U1V2",
      "businessId": "01J9Z3K2M4N5P6Q7R8S9T0U1V3",
      "businessName": "Acme Plumbing",
      "businessSlug": "acme-plumbing",
      "name": "Acme Plumbing",
      "description": "Residential and commercial plumbing services.",
      "categories": ["home-services", "plumbing"],
      "tags": ["licensed", "24-7"],
      "featuredImageUrl": "https://cdn.ezforge.ai/listings/acme-plumbing.jpg",
      "city": "Detroit",
      "state": "MI",
      "publishedAt": "2026-03-01T12:00:00Z",
      "verificationLevel": "business_verified",
      "relevanceScore": 43
    }
  ],
  "meta": {
    "cursor": "eyJpZCI6IjAxSjlaM0syTTRONVA2UTdSOFM5VDBVMVY0In0=",
    "hasMore": true,
    "total": 42
  }
}

Response fields:

Field	Type	Description
`verificationLevel`	string	Verification tier: `unverified`, `phone_verified`, `business_verified`, or `premium_verified`
`relevanceScore`	integer	Computed relevance score (higher = more relevant in directory ranking)

Get directory listing

GET /v1/directory/:id

Returns the full detail for a single active listing, including MCP server URL and industry metadata. No authentication required. Path parameters:

Parameter	Description
`id`	Directory listing ID (ULID)

Response 200:

{
  "data": {
    "id": "01J9Z3K2M4N5P6Q7R8S9T0U1V2",
    "businessId": "01J9Z3K2M4N5P6Q7R8S9T0U1V3",
    "businessName": "Acme Plumbing",
    "businessSlug": "acme-plumbing",
    "name": "Acme Plumbing",
    "description": "Residential and commercial plumbing services.",
    "categories": ["home-services", "plumbing"],
    "tags": ["licensed", "24-7"],
    "featuredImageUrl": "https://cdn.ezforge.ai/listings/acme-plumbing.jpg",
    "city": "Detroit",
    "state": "MI",
    "publishedAt": "2026-03-01T12:00:00Z",
    "verificationLevel": "business_verified",
    "relevanceScore": 43,
    "mcpServerUrl": "https://acme-plumbing.ezforge.run",
    "industry": "plumbing",
    "website": "https://acmeplumbing.example.com"
  }
}

Response fields:

Field	Type	Description
`verificationLevel`	string	Verification tier: `unverified`, `phone_verified`, `business_verified`, or `premium_verified`
`relevanceScore`	integer	Computed relevance score (higher = more relevant in directory ranking)

Errors:

Code	Description
`404`	Listing not found or not active

Update directory visibility

PATCH /v1/directory/:id

Opts a business in or out of the public directory. The authenticated user must own the business associated with the listing. Setting visible: true activates the listing and records publishedAt on first publication (subsequent activations preserve the original publishedAt). Setting visible: false returns the listing to pending status and hides it from public reads. Authentication: Session cookie (dashboard login). API key auth is not supported for this endpoint. Path parameters:

Parameter	Description
`id`	Directory listing ID (ULID)

Request body:

{
  "visible": true
}

Field	Type	Required	Description
`visible`	boolean	Yes	`true` to activate (opt in), `false` to deactivate (opt out)

Response 200:

{
  "data": {
    "id": "01J9Z3K2M4N5P6Q7R8S9T0U1V2",
    "businessId": "01J9Z3K2M4N5P6Q7R8S9T0U1V3",
    "status": "active",
    "publishedAt": "2026-03-01T12:00:00Z",
    "updatedAt": "2026-03-26T10:00:00Z"
  }
}

Errors:

Code	Description
`401`	Not authenticated
`404`	Listing not found or not owned by the authenticated user
`422`	`visible` field missing or not a boolean

MCP server metadata

GET /.well-known/mcp-server-metadata

Returns structured metadata for a Ready MCP server identified by its subdomain. This endpoint is used by AI agents during server discovery. No authentication required. Query parameters:

Parameter	Required	Description
`subdomain`	Yes	MCP server subdomain (e.g. `acme-plumbing.ezforge.run`)

Response 200:

{
  "name": "Acme Plumbing MCP Server",
  "version": "1.0.0",
  "description": "Residential and commercial plumbing services.",
  "mcpServerUrl": "https://acme-plumbing.ezforge.run",
  "vertical": "plumbing",
  "agentDiscovery": {
    "oauthProtectedResource": "https://acme-plumbing.ezforge.run/.well-known/oauth-protected-resource",
    "openaiTransport": "http",
    "geminiConnectionType": "StreamableHTTP",
    "mcpSpecVersion": "2025-11-25"
  },
  "business": {
    "id": "01J9Z3K2M4N5P6Q7R8S9T0U1V3",
    "name": "Acme Plumbing",
    "slug": "acme-plumbing",
    "industry": "plumbing",
    "city": "Detroit",
    "state": "MI",
    "verificationLevel": "business_verified",
    "accountAgeDays": 127,
    "profileCompleteness": 85,
    "lastUpdated": "2026-03-26T10:00:00Z",
    "interactionCount": 342
  }
}

Top-level fields:

Field	Type	Description
`vertical`	string or `null`	Business industry/template type (mirrors `business.industry`); exposed at the top level so agent crawlers can identify the business type without parsing the nested `business` object

agentDiscovery fields:

Field	Type	Description
`oauthProtectedResource`	string	OAuth 2.1 PKCE discovery URL (RFC 9728) — used by Claude, ChatGPT, and Gemini to begin authorization
`openaiTransport`	string	Transport hint for the OpenAI Responses API: `"http"` (stateless JSON-RPC POST, recommended) or `"sse"` (streaming SSE)
`geminiConnectionType`	string	Transport hint for Gemini ADK: `"StreamableHTTP"` maps to `StreamableHTTPServerParams`
`mcpSpecVersion`	string	MCP spec revision advertised by this server (currently `"2025-11-25"`)

Trust signals (EP-R17):

Field	Type	Description
`verificationLevel`	string	Current verification tier (`unverified`, `phone_verified`, `business_verified`, `premium_verified`)
`accountAgeDays`	integer	Days since the business account was created
`profileCompleteness`	integer	Profile completeness percentage (0–100)
`lastUpdated`	string (ISO 8601)	Timestamp of the most recent directory listing update
`interactionCount`	integer	Total analytics events recorded for this business

Errors:

Code	Description
`400`	`subdomain` query parameter is missing
`404`	No active listing found for the given subdomain

`VerificationLevel` type

The VerificationLevel string type is used across all directory responses to represent a business’s verification status.

Value	Meaning
`unverified`	No verification completed
`phone_verified`	Business phone number confirmed via SMS
`business_verified`	Business identity confirmed (30-day account + phone verification)
`premium_verified`	Highest trust level, awarded after manual review by ezForge

See Business Verification for the full tier progression and how to earn each level.

​List directory

​Get directory listing

​Update directory visibility

​MCP server metadata

​VerificationLevel type

List directory

Get directory listing

Update directory visibility

MCP server metadata

`VerificationLevel` type