{"openapi":"3.1.0","info":{"title":"Directory","version":"0.0.0"},"paths":{"/health":{"get":{"operationId":"getHealth","responses":{"200":{"description":"Process is up","content":{"application/json":{"example":{"ok":true}}}}}}},"/api/v1":{"get":{"operationId":"getApiV1","responses":{"200":{"description":"API index","content":{"application/json":{"example":{"name":"directory","schemaVersion":null}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","responses":{"200":{"description":"This document","content":{"application/json":{"example":{"openapi":"3.1.0"}}}}}}},"/developers":{"get":{"operationId":"getDevelopers","responses":{"200":{"description":"HTML docs","content":{"text/html":{"example":"<h1>Developers</h1>"}}}}}},"/developers/changelog":{"get":{"operationId":"getDevelopersChangelog","responses":{"200":{"description":"HTML API changelog, newest first","content":{"text/html":{"example":"<h1>API Changelog</h1>"}}}}}},"/api/v1/pages/city":{"get":{"operationId":"getCityPageDto","parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string"}},{"name":"region","in":"query","required":true,"schema":{"type":"string"}},{"name":"city","in":"query","required":true,"schema":{"type":"string"}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"facet","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"City × category DTO for SEO pages with at least 3 published listings","content":{"application/json":{"example":{"ok":true,"page":{"country":"us","region":"ny","city":"new-york","cityName":"New York City","category":"plumbers","total":5,"title":"Licensed Plumbers in New York City | HomeCrafto","description":"Verified licensed plumbers in New York City.","canonicalUrl":"https://homecrafto.com/us/ny/new-york/plumbers","breadcrumbs":[{"name":"Home","url":"https://homecrafto.com/"},{"name":"United States","url":"https://homecrafto.com/us"},{"name":"New York","url":"https://homecrafto.com/us/ny"},{"name":"New York City","url":"https://homecrafto.com/us/ny/new-york"}],"items":[{"id":"plumber-101","name":"NYC Master Plumbing Co","address":"123 Broadway, New York, NY 10001","city":"New York","region":"ny","category":"plumbers"}]}}}}},"404":{"description":"City page does not meet the index gate (minimum 3 published listings required) or does not exist","content":{"application/json":{"example":{"error":{"code":"NOT_FOUND","message":"City page does not meet the index gate or does not exist.","docs":"https://homecrafto.com/developers/errors#not-found"}}}}}}}},"/api/v1/listings":{"get":{"operationId":"listListings","responses":{"200":{"description":"Empty until a golden push","content":{"application/json":{"example":{"items":[]}}}}}}},"/api/v1/search":{"get":{"operationId":"searchListings","responses":{"200":{"description":"Search listings by radius from a location or ZIP code","content":{"application/json":{"example":{"origin":{"zip":"06903","city":"Stamford","state":"CT","lat":41.136,"lng":-73.5711},"radiusMiles":25,"total":1,"items":[{"id":"ctdph-1390821","name":"NEW CANAAN VETERINARY HOSPITAL","category":"veterinarians","city":"New Canaan","region":"ct","address":"7 VITTI ST, New Canaan, CT 06840","distanceMiles":4.1}],"surroundingCities":[{"city":"New Canaan","count":1,"minDistance":4.1}]}}}}}}},"/api/v1/search/autocomplete":{"get":{"operationId":"autocompleteSearch","responses":{"200":{"description":"Fast prefix suggestions for location and category search","content":{"application/json":{"example":{"query":"Pari","suggestions":[{"text":"Paris, France","city":"Paris","country":"FR"},{"text":"Pastelería Ideal","city":"Ciudad de México","country":"MX"}]}}}}}}},"/api/v1/claims":{"post":{"operationId":"submitClaim","responses":{"200":{"description":"Submit an ownership or management claim for a published business listing","content":{"application/json":{"example":{"ok":true,"claimId":"claim-12345","status":"pending","submittedAt":"2026-10-21T00:00:00.000Z"}}}}}}},"/api/v1/claims/status":{"get":{"operationId":"getClaimStatus","responses":{"200":{"description":"Check the review status of a submitted listing claim","content":{"application/json":{"example":{"claimId":"claim-12345","status":"approved","updatedAt":"2026-10-21T00:00:00.000Z"}}}}}}},"/api/v1/editions":{"get":{"operationId":"listEditorialEditions","responses":{"200":{"description":"Localized tourism editorial editions (NYC, Miami, Mexico, Global)","content":{"application/json":{"example":{"activeEdition":"global","editions":[{"id":"nyc","brandName":"FinderNYC","domain":"findernyc.com","cityLabel":"New York City","countryCode":"us","language":"en"}]}}}}}}},"/api/v1/spots":{"get":{"operationId":"listEditorialSpots","responses":{"200":{"description":"Curated insider city spots filtered by edition, country, city, category, vibe, or neighborhood","content":{"application/json":{"example":{"total":1,"items":[{"slug":"bistrot-paul-bert-paris-11e","edition":"global","country":"fr","category":"restaurant","city":"Paris","title":"Iconic Zinc-Counter Parisian Bistrot in the 11th Arrondissement","replicaPlaceHref":"/fr/places/fr-alim-7511101","registryBadge":"Alim'confiance · FR-ALIM-7511101"}]}}}}}}},"/api/v1/neighborhoods":{"get":{"operationId":"listEditorialNeighborhoods","responses":{"200":{"description":"Neighborhood vibe guides filtered by edition, country, city, or area","content":{"application/json":{"example":{"total":1,"items":[{"slug":"east-village","edition":"nyc","country":"us","city":"New York City","name":"East Village","area":"Manhattan, NY"}]}}}}}}},"/api/v1/chains":{"get":{"operationId":"listLocalChains","responses":{"200":{"description":"Curated 3-stop local walking routes filtered by edition, country, city, neighborhood, spot, or mood","content":{"application/json":{"example":{"total":1,"items":[{"slug":"lic-sunset-to-astoria-feast","edition":"nyc","country":"us","title":"Queens Golden Hour to Greek Seafood Feast","neighborhood":"Long Island City","mood":"Sunset Views & Chill Drinks"}]}}}}}}},"/api/v1/billing/checkout":{"post":{"operationId":"startCheckout","security":[{"staff":[]}],"responses":{"404":{"description":"Disabled until the page row and the host secret exist","content":{"application/json":{"example":{"error":"not-found"}}}}}}},"/api/v1/mcp":{"post":{"operationId":"callExternalMcp","security":[{"staff":[]}],"responses":{"200":{"description":"External tools whose handlers finish","content":{"application/json":{"example":{"tools":["health","listings.search"]}}}}}}},"/privacy":{"get":{"operationId":"getPrivacy","responses":{"200":{"description":"Privacy fixture","content":{"text/html":{"example":"<h1>Privacy</h1>"}}}}}},"/terms":{"get":{"operationId":"getTerms","responses":{"200":{"description":"Terms fixture","content":{"text/html":{"example":"<h1>Terms</h1>"}}}}}},"/robots.txt":{"get":{"operationId":"getRobots","responses":{"200":{"description":"Crawler policy with no sitemap line","content":{"text/plain":{"example":"User-agent: *\nDisallow:\n"}}}}}},"/api/admin/billing/pages":{"get":{"operationId":"listBillingPages","security":[{"staff":[]}],"responses":{"200":{"description":"Page rows without secrets","content":{"application/json":{"example":{"pages":[],"webhook":false}}}}}},"put":{"operationId":"putBillingPage","security":[{"staff":[]}],"responses":{"400":{"description":"Rejected when the host has no Stripe secret","content":{"application/json":{"example":{"status":400}}}}}}},"/api/admin/audits":{"get":{"operationId":"listAudits","security":[{"staff":[]}],"responses":{"200":{"description":"Audit rows","content":{"application/json":{"example":{"audits":[]}}}}}}},"/api/admin/staff/grant":{"post":{"operationId":"grantStaff","security":[{"staff":[]}],"responses":{"401":{"description":"No session","content":{"application/json":{"example":{"status":401}}}}}}},"/api/admin/staff/revoke":{"post":{"operationId":"revokeStaff","security":[{"staff":[]}],"responses":{"401":{"description":"No session","content":{"application/json":{"example":{"status":401}}}}}}},"/api/admin/mcp":{"post":{"operationId":"callInternalMcp","security":[{"staff":[]}],"responses":{"200":{"description":"Internal tool call, dry-run unless dryRun is false","content":{"application/json":{"example":{"dryRun":true}}}}}}},"/admin":{"get":{"operationId":"getAdmin","security":[{"staff":[]}],"responses":{"401":{"description":"No session","content":{"application/json":{"example":{"error":"unauthorized"}}}}}}},"/health/deep":{"get":{"operationId":"getHealthDeep","responses":{"200":{"description":"Deep health check with edge telemetry and moderation counters","content":{"application/json":{"example":{"ok":true,"status":"healthy","host":"homecrafto.com","brand":"HomeCrafto","vertical":"trade","edge":{"colo":"EWR","country":"US","uptimeSeconds":3600},"outbox":{"indexNowPending":0,"claimsPending":0},"rateLimiter":{"trackedIps":0}}}}}}}},"/api/v1/telemetry/metrics":{"get":{"operationId":"getTelemetryMetrics","responses":{"200":{"description":"Real-time aggregated edge performance and request telemetry","content":{"application/json":{"example":{"totalRequests":100,"statusBreakdown":{"2xx":95,"3xx":2,"4xx":3,"5xx":0},"latency":{"p50":1.2,"p95":14.5,"mean":2.1,"min":0.1,"max":25},"botBreakdown":{"human":80,"searchEngine":15,"aiScraper":5,"malicious":0},"cacheHitRatio":0.85,"zeroTokenSpendVerified":true,"timestamp":"2026-10-21T12:00:00.000Z"}}}}}}},"/api/v1/telemetry/logpush":{"get":{"operationId":"getTelemetryLogpush","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Buffered structured Cloudflare Logpush event stream","content":{"application/json":{"example":{"ok":true,"count":1,"events":[{"Event":"WorkerRequest","EventTimestampMs":1729512000000,"Outcome":"ok","RayId":"9a12b34c-EWR","Script":"directory-pet","Request":{"Method":"GET","URL":"https://sociablepet.com/us/ct/stamford","Country":"US","Colo":"EWR"},"Response":{"Status":200,"DurationMs":1.5,"CacheStatus":"HIT"},"Metadata":{"Brand":"pet","BotType":"human","ZeroTokenSpend":true}}]}}}}}}},"/api/v1/claim/magic-link":{"post":{"operationId":"postClaimMagicLink","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claimId","email"],"properties":{"claimId":{"type":"string"},"email":{"type":"string"}}},"example":{"claimId":"claim_123","email":"owner@example.com"}}}},"responses":{"200":{"description":"Cryptographically signed magic link for provider self-service","content":{"application/json":{"example":{"ok":true,"claimId":"claim_123","magicUrl":"https://homecrafto.com/claim/magic-verify?token=example_token","status":"pending"}}}}}}},"/staff/login":{"get":{"operationId":"getStaffLogin","security":[{"staff":[]}],"responses":{"200":{"description":"Buttons hidden until that host has a client id","content":{"application/json":{"example":{"google":false,"apple":false,"password":false}}}}}}}},"components":{"securitySchemes":{"staff":{"type":"apiKey","in":"cookie","name":"directory_session"}}}}