> ## Documentation Index > Fetch the complete documentation index at: https://docs.ezforge.ai/llms.txt > Use this file to discover all available pages before exploring further. # Directory > Public directory of Ready-powered businesses 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](/ready/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`:** ```json theme={null} { "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`:** ```json theme={null} { "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:** ```json theme={null} { "visible": true } ``` | Field | Type | Required | Description | | --------- | ------- | -------- | ------------------------------------------------------------ | | `visible` | boolean | Yes | `true` to activate (opt in), `false` to deactivate (opt out) | **Response `200`:** ```json theme={null} { "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`:** ```json theme={null} { "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](/ready/verification) for the full tier progression and how to earn each level.