---
title: "A domain's verified door (#54)"
method: GET
path: "/agent/resolve"
tags: ["discovery"]
---

# A domain's verified door (#54)

`GET /agent/resolve`

## Request

- Base URL: `https://api.bubblio.dev`
- URL: `https://api.bubblio.dev/agent/resolve`
- Auth: none declared

"I know only the platform's domain — which door?" The answer is VERIFIED or it is
nothing: the resolver crawls the domain's OWN breadcrumbs (an /mcp redirect,
llms.txt's first 40 lines, /.well-known/mcp — at most 3 guarded fetches, 4s each,
redirects confined to the domain's own name tree), and a pointer served from the
domain IS the proof, because only the domain's owner can serve one. Self-declared
data (door labels, callback URLs) is never consulted and never echoed — an approved
account naming itself "Stripe" can never make this endpoint say so. A pointer at a
door that is not live answers EXACTLY like no pointer at all: closed and nonexistent
read the same here, as at the door's own 404.

Cost control: the per-caller bucket is spent on EVERY answered request (default
30/hour — cached answers and domain-bucket 429s included, so hammering a crawl-
limited domain runs down the caller's own budget); the crawl itself runs only on a
cache miss, behind a per-target-domain bucket (default 10/hour, shared across all
callers). The 15-minute cache stores the crawl result, never the verdict — door
liveness is re-checked on every answer, so a door closed a minute ago stops
verifying immediately while its domain keeps its crawl quota.

## Query parameters

- `domain` string, required

## Response `200`

The verified door, or the one honest miss — "no pointer" and "pointer at a dead
door" are indistinguishable, and other doors are never mentioned.

- union
  - object: Verified — the domain's own pointer named a live door.
    - `domain` string, required
    - `verified` true, required
    - `door` object, required
      - `label` string, required
      - `handle` string, required
      - `door_id` string, required
      - `mcp` string, uri, required
      - `manifest` string, uri, required
      - `llms` string, uri, required
  - object: The uniform miss, teaching the street sign.
    - `domain` string, required
    - `verified` false, required
    - `notice` string, required: Points a domain owner at bubblio.dev/docs/discovery#street-sign.

## Other responses

- `400`: Not a bare registrable hostname, or one of Bubblio's own.
- `429`: Either bucket tripped — the per-caller ceiling, or the per-domain crawl ceiling on a cache miss. The message names which; Retry-After is clamped.

---

[API](https://skmtc.dev/bubblio/apis/bubblio-agent-door-api.md) · [All operations](https://skmtc.dev/bubblio/apis/bubblio-agent-door-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bubblio/apis/bubblio-agent-door-api/revisions/d858aff9c01d?raw)