Skip to main content
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:
OperationTierLimit
GET /v1/directorydirectory300 req/min per IP
GET /v1/directory/:iddirectory300 req/min per IP
PATCH /v1/directory/:idUser plan tierPlan default

​
List directory

GET /v1/directory
Returns a paginated list of active Ready-powered business listings. No authentication required. Query parameters:
ParameterTypeDefaultDescription
limitinteger20Max items to return (1–100)
cursorstring—Opaque cursor from previous response
searchstring—Fuzzy search against listing name
categorystring—Exact category match (listing must include this value)
locationstring—Partial match against city or state
templateTypestring—Exact match against business industry/template type
verticalstring—Alias for templateType (e.g. salon, home-services)
citystring—Exact city match (case-insensitive)
latnumber—Latitude for geolocation search (requires lng and radius_miles)
lngnumber—Longitude for geolocation search (requires lat and radius_miles)
radius_milesnumber—Radius in miles for geolocation search
min_verificationstring—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:
FieldTypeDescription
verificationLevelstringVerification tier: unverified, phone_verified, business_verified, or premium_verified
relevanceScoreintegerComputed 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:
ParameterDescription
idDirectory 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:
FieldTypeDescription
verificationLevelstringVerification tier: unverified, phone_verified, business_verified, or premium_verified
relevanceScoreintegerComputed relevance score (higher = more relevant in directory ranking)
Errors:
CodeDescription
404Listing 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:
ParameterDescription
idDirectory listing ID (ULID)
Request body: 
{
  "visible": true
}
FieldTypeRequiredDescription
visiblebooleanYestrue 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:
CodeDescription
401Not authenticated
404Listing not found or not owned by the authenticated user
422visible 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:
ParameterRequiredDescription
subdomainYesMCP 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",
  "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
  }
}
Trust signals (EP-R17):
FieldTypeDescription
verificationLevelstringCurrent verification tier (unverified, phone_verified, business_verified, premium_verified)
accountAgeDaysintegerDays since the business account was created
profileCompletenessintegerProfile completeness percentage (0–100)
lastUpdatedstring (ISO 8601)Timestamp of the most recent directory listing update
interactionCountintegerTotal analytics events recorded for this business
Errors:
CodeDescription
400subdomain query parameter is missing
404No 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.
ValueMeaning
unverifiedNo verification completed
phone_verifiedBusiness phone number confirmed via SMS
business_verifiedBusiness identity confirmed (30-day account + phone verification)
premium_verifiedHighest trust level, awarded after manual review by ezForge
See Business Verification for the full tier progression and how to earn each level.