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`	300 req/min per IP
`GET /v1/directory/:id`	`directory`	300 req/min per IP
`PATCH /v1/directory/:id`	User plan tier	Plan default

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