Outcome
Resolve an intended deployment hostname to its saved canonical application identity, keeping identification separate from access and availability.
GET /api/services/by-host
Before you start
This public action declares no permission and performs a saved directory identity lookup, not caller authentication, organization selection, app assignment or launch authorization. Its returned canonical app id supplies no grant.
For CLI/MCP always send the explicit intended deployment hostname in the required host input. Do not assume the API request Host header, browser origin or another service label identifies the app you mean. Discover later app actions/resources and caller permissions independently.
Examples are complete source-derived synthetic UNRUN responses with fictional .invalid hosts and assumed saved directory rows. No real DNS, host, app, private record or business operation was queried, and no application import/test/runtime probe was executed.
Input and response
Action: app_topolo_developers.catalog.identity.resolve_by_host.
HTTP200 is exactly {success:true,data:{app_id,app_slug,app_name}}. These are canonical application identity fields, despite the legacy /api/services path name. There is no separate service id, human permission, workspace, deployment version or health result in this body.
Native input requires host as a string of1-2048 characters and forbids other fields. This is not full hostname semantic validation. The handler trims/lowercases the supplied value, uses URL.hostname when a scheme URL parses, then strips path and a trailing numeric port. The directory helper normalizes it again for exact saved-host matching.
A host can match the registered primary host or alias in app_directory_hosts joined to app_directory. This source lookup does not apply marketplace-public, non-retired or non-sunset filters; identity discovery alone does not prove the app is listed, active, deployed at that moment or accessible to this caller.
The source performs no DNS resolution, target-host request, certificate check, host ownership challenge or app healthcheck for this query. It trusts its saved directory association; any ambiguity or unexpected mapping needs the existing registry owner, not a guessed identity override.
Raw HTTP can fall back to its own request Host header when explicit host is absent/empty. That is not the requesting browser Origin, and can identify the API/proxy host instead of the intended application. The published native action still requires explicit host, so do not omit it or use a forwarded header to bypass its schema.
No normalized host returns rawHTTP400 {success:false,error:"host required"}; no saved match returns rawHTTP404 {success:false,error:"Not found"}. These raw error values are strings, unlike console routes with error.message. The published success-only output schema is not the raw error schema; retain actual status/body rather than inventing a stable error.code.
OPTIONS204 is CORS preflight, not identity success. A non-GET method gets405 with its raw method error; that is not an alternate mutation operation. Unexpected directory/storage failure has no uniform catch envelope defined here, so do not report it as a404 or empty success.
Worked requests and responses
Resolve a registered fictional host
Complete synthetic UNRUN HTTP200 assuming this exact primary/alias host is saved against the shown app directory row. The .invalid host is fictional; no DNS or live service call occurred.
Input:
{
"host": "fixture.example.invalid"
}
Response:
{
"success": true,
"data": {
"app_id": "app_docs_fixture",
"app_slug": "fixture",
"app_name": "Fixture"
}
}
Retain canonical app_id/slug/name for the intended app, then discover actual resource and caller authorization separately.
A URL resolves to the same hostname
Complete synthetic UNRUN HTTP200 under the same saved fixture association. URL hostname normalization removes scheme, port/path/query and lowercases the host; it does not visit that URL or verify it is controlled by the caller.
Input:
{
"host": "https://Fixture.Example.invalid:8443/a/path?x=1"
}
Response:
{
"success": true,
"data": {
"app_id": "app_docs_fixture",
"app_slug": "fixture",
"app_name": "Fixture"
}
}
Verify the returned app is the intended saved association; do not mistake successful normalization for target ownership or access.
Whitespace has no usable hostname
Complete synthetic UNRUN rawHTTP400. One space passes native string minLength1 but normalizes empty in the handler. The raw error is a string and is outside the success-only output schema.
Input:
{
"host": " "
}
Response:
{
"success": false,
"error": "host required"
}
Supply the actual intended hostname; do not guess a different host or manufacture a successful identity.
An unknown host has no saved match
Complete synthetic UNRUN rawHTTP404 assuming no saved directory host association. This does not prove the domain does not exist, the app is retired or the caller lacks a permission.
Input:
{
"host": "unregistered.example.invalid"
}
Response:
{
"success": false,
"error": "Not found"
}
Confirm the intended environment/deployment host with its existing owner; do not hardcode an unverified app id or create another identity.
Verify and recover
-
Confirm the exact canonical app_id, app_slug and display app_name correspond to the intended environment/host association. Do not synthesize a service id or add a Topolo prefix to the display name.
-
Use current authenticated application/action/resource discovery for any intended operation. Public identity resolution proves neither entitlement, workspace membership, runtime health, DNS/certificate ownership nor deployment-source version.
-
On actual400/404/storage failure, retain original hostname/environment and raw status/body. Ask the existing registry/deployment owner to reconcile a missing/wrong mapping; do not mutate identity or use a proxy header as a grant.
-
No inverse is needed for this identity read. It creates no host registration, app, credential, workspace or deployment; any registration correction requires its separate supported owner workflow.
Change log
- 2026-10-21: Added exact canonical identity response, explicit-host versus raw Host fallback, normalization/alias and raw-error boundaries, with complete synthetic unrun examples.