Fixing the AgentOS API URL Path Mismatch — v0.1.63

Released: 2026-04-04
Severity: Critical bug fix
Files changed: company.ts, features.ts, accounts.ts, affiliate.ts, landlord.ts + 5 test files
Scale: 18 endpoint paths corrected, 239 additions, 863 deletions

---

What Happened

Every outbound HTTP call in the src/lib/letmc/ integration layer was hitting URLs that don't exist on live-api.letmc.com. The paths were constructed using a /v3/{shortName}/{namespace}/ prefix pattern left over from an earlier API version assumption — for example:

GET /v3/acme-lettings/lettings/landlords?emailAddress=user@example.com

The AgentOS API does not serve any routes under /v3/. The correct path structure is:

GET /acme-lettings/landlord?email=user@example.com

This caused 404 Not Found responses on virtually every portal feature — landlord dashboards, tenant lookups, buyer and vendor discovery, company verification, branding, branch listings, affiliate links, and feature flag overrides.

---

What Changed

URL Structure

The AgentOS API path format is:

/{clientName}/{resource}[/{id}][?params]

Three specific mistakes were corrected across the codebase:

1. Removed /v3/ prefix — no version prefix exists in the real API.
2. Removed namespace segments — /lettings/ and /sales/ area prefixes do not exist. Resource types are addressed directly (e.g. landlord, not lettings/landlords).
3. Entity names are singular — landlord, tenant, buyer, vendor, contractor (not the plural forms used previously).

Query Parameter Rename (accounts.ts)

The email search parameter was renamed from emailAddress to email:

# Before
GET /v3/{shortName}/lettings/landlords?emailAddress=user@example.com&offset=0&count=50

# After
GET /{clientName}/landlord?email=user@example.com

The offset and count pagination parameters have also been removed from account lookup calls.

Branch Fetching Simplified (company.ts)

Previously, getCompanyBranches made two parallel requests — one for lettings branches and one for sales branches — then merged the results into a single map keyed by branch ID:

// Before — two parallel requests
const [lettingsResult, salesResult] = await Promise.allSettled([
  letmcClient.get(`/v3/${shortName}/lettings/branches?offset=0&count=100`),
  letmcClient.get(`/v3/${shortName}/sales/branches?offset=0&count=100`),
]);
// ... merge logic ...

The unified /{clientName}/company/branches endpoint returns both lettings and sales portal URLs in a single response, removing the need for the merge step:

// After — single request
const response = await letmcClient.get(
  `/${shortName}/company/branches?offset=0&count=100`
);

Each branch record now includes both LettingsPortalUrl and SalesPortalUrl directly.

Company Verification Endpoint (company.ts)

The company existence check now targets the dedicated verify endpoint:

# Before
GET /v3/{shortName}/company

# After
GET /{clientName}/company/verify

---

Full Endpoint Reference

The corrected AgentOS API paths used by the src/lib/letmc/ layer are:

Function	Method	Path
verifyCompany	GET	/{clientName}/company/verify
getCompanyBranding	GET	/{clientName}/company/branding
getCompanyBranches	GET	/{clientName}/company/branches
getCompanyCurrency	GET	/{clientName}/company/currency
getCompanyEnums	GET	/{clientName}/company/enums/{type}
getFeatureOverrides	GET	/{clientName}/overrides
getFixfloOverrides	GET	/{clientName}/overrides/fixflo/{personId}
discoverAccounts (landlord)	GET	/{clientName}/landlord?email={email}
discoverAccounts (tenant)	GET	/{clientName}/tenant?email={email}
discoverAccounts (buyer)	GET	/{clientName}/buyer?email={email}
discoverAccounts (vendor)	GET	/{clientName}/vendor?email={email}
discoverAccounts (contractor)	GET	/{clientName}/contractor?email={email}
getAffiliateLinks	GET	/{clientName}/affiliates/{personType}
getLandlordProperties	GET	/{clientName}/landlord/{id}/properties
getLandlordTenancies	GET	/{clientName}/landlord/{id}/tenancies
getLandlordStatements	GET	/{clientName}/landlord/{id}/statements
getMaintenanceJob	GET	/{clientName}/maintenancejobs/{id}
getProperty	GET	/{clientName}/properties/{id}
getTenancy	GET	/{clientName}/tenancies/{id}

Note: payment-request.ts already used the correct path (/{clientName}/payments/requests/{personID}) and was not modified in this release.

---

What's Still Pending

The following files still contain /v3/ paths and will be corrected in follow-up releases:

• tenant.ts
• buyer.ts
• vendor.ts
• contractor.ts
• messaging.ts
• document.ts
• maintenance.ts

Portal features that depend solely on these files may still return 404 until those follow-up fixes are shipped.