{"openapi":"3.0.3","info":{"title":"404.directory","description":"Agent Discovery + Trust infrastructure. Discover via MCP/REST, call first-party tools, and inspect or invoke curated read-only remote MCP tools through the controlled gateway. Registry writes require Bearer auth.","version":"0.9.2"},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"REGISTRY_ADMIN_TOKEN or provider_api_key from POST /v1/tools"}},"schemas":{"JsonValue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"string","nullable":true,"enum":[null]},{"type":"array","items":{"$ref":"#/components/schemas/JsonValue"}},{"type":"object","additionalProperties":{"$ref":"#/components/schemas/JsonValue"}}]}}},"paths":{"/health":{"get":{"summary":"Service health check","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["status","version","tools","browser_egress","catalog"],"properties":{"status":{"type":"string","enum":["ok"]},"version":{"type":"string"},"catalog":{"type":"boolean"},"browser_egress":{"type":"string","enum":["pinned_ip_proxy"]},"tools":{"type":"array","items":{"type":"string"}}}}}}}}}},"/tools":{"get":{"summary":"List registered tools","description":"Compact low-token tool discovery. Follow href for full metadata and schemas.","responses":{"200":{"description":"Default Response"}}}},"/tools/{name}":{"get":{"summary":"Get one registered tool","parameters":[{"schema":{"type":"string"},"in":"path","name":"name","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/understand":{"post":{"operationId":"understand_webpage","summary":"Understand webpage","tags":["tools"],"description":"Reads one public human-facing webpage and returns a compact, evidence-linked AgentPageModel: page type, entities, login/current state, forms, enabled actions, and confidence. Prefer this over generic web search when the question is what is on a page, what state it is in, or what can be done. Observes only — never clicks, logs in, orders, or pays.\n\nWhen to use: Use when a user asks you to understand a specific public webpage's contents, entities, forms, login wall, current state, or available actions. Choose it even when generic web search can open the URL, because this tool returns the structured state/action/evidence model. Do not replace a suitable Agent-native API.\n\nDo not use when: Do not use only to check whether a deployment is live, to verify an HTTP status or exact text, or when a stable structured API already provides the required data. It cannot access private or authenticated pages.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false},"example":{"url":"https://example.com"}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"page_type":{"type":"string","enum":["product","article","hotel","job","order","search_results","login","form","homepage","other"]},"summary":{"type":"string","minLength":1,"maxLength":2000},"entities":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["product","article","hotel","job","order","organization","person","place","other"]},"name":{"type":"string","minLength":1,"maxLength":500},"attributes":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/JsonValue"}},"evidence_ids":{"maxItems":10,"type":"array","items":{"type":"string","maxLength":40}}},"required":["type","name","attributes"],"additionalProperties":false}},"state":{"type":"object","properties":{"login_status":{"type":"string","enum":["authenticated","anonymous","unknown"]},"properties":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/JsonValue"}},"evidence_ids":{"maxItems":10,"type":"array","items":{"type":"string","maxLength":40}}},"required":["login_status","properties"],"additionalProperties":false},"actions":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["search","login","select_variant","add_to_cart","submit","download"]},"label":{"type":"string","minLength":1,"maxLength":300},"target":{"type":"string","maxLength":500},"enabled":{"type":"boolean"},"required_inputs":{"maxItems":30,"type":"array","items":{"type":"string","maxLength":200}},"evidence_ids":{"maxItems":10,"type":"array","items":{"type":"string","maxLength":40}}},"required":["type","label","enabled","required_inputs"],"additionalProperties":false}},"evidence":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":40},"source":{"type":"string","enum":["url","title","meta","visible_text","semantic_dom","accessibility","json_ld","form","control","link","llm"]},"field":{"type":"string","maxLength":200},"role":{"type":"string","maxLength":100},"label":{"type":"string","maxLength":500},"raw_value":{"allOf":[{"$ref":"#/components/schemas/JsonValue"}]},"supports":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":100}}},"required":["source"],"additionalProperties":false}},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["page_type","summary","entities","state","actions","evidence","confidence"],"additionalProperties":false},"example":{"page_type":"homepage","summary":"Example Domain — documentation example page.","entities":[],"state":{"login_status":"unknown","properties":{},"evidence_ids":["e1"]},"actions":[],"evidence":[{"id":"e1","source":"title","field":"title","raw_value":"Example Domain","supports":["state"]}],"confidence":0.7}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}}}},"408":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}}}}}}},"/verify/web":{"post":{"operationId":"verify_web","summary":"Verify web","tags":["tools"],"description":"Independently verifies that a public website is reachable and meets deployment expectations (HTTP status, HTTPS validity, optional expected text). Returns structured evidence for accept / retry / escalate decisions.\n\nWhen to use: Use when the user explicitly asks to verify a deployment claim, public reachability, final HTTP status, HTTPS/TLS, redirects, or exact expected text. Prefer expected_text that distinguishes the new version (build id, version string, unique copy).\n\nDo not use when: Do not call this merely before or alongside understand_webpage to prove that its target is reachable; a successful understand_webpage result already proves the page was fetched. Do not use to extract entities, forms, actions, or meaning, for private/internal URLs, or for subjective visual-quality judgments.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public HTTP(S) URL to verify, for example https://example.com"},"expected_status":{"type":"integer","minimum":100,"maximum":599,"description":"Expected final HTTP status code, for example 200"},"expected_text":{"description":"Optional response text that proves the intended version or state is live","type":"string","maxLength":2000}},"required":["url","expected_status"],"additionalProperties":false},"example":{"url":"https://example.com","expected_status":200,"expected_text":"Example Domain"}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"verified":{"type":"boolean"},"checks":{"type":"object","properties":{"reachable":{"type":"boolean"},"status":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"https_valid":{"type":"boolean"},"text_found":{"type":"boolean"}},"required":["reachable","status","https_valid","text_found"],"additionalProperties":false},"evidence":{"type":"object","properties":{"requested_url":{"type":"string","format":"uri"},"final_url":{"nullable":true,"type":"string","format":"uri"},"http":{"type":"object","properties":{"status":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expected_status":{"type":"integer","minimum":100,"maximum":599},"matched":{"type":"boolean"}},"required":["status","expected_status","matched"],"additionalProperties":false},"expected_text":{"type":"object","properties":{"value":{"nullable":true,"type":"string","maxLength":2000},"checked":{"type":"boolean"},"matched":{"nullable":true,"type":"boolean"}},"required":["value","checked","matched"],"additionalProperties":false},"tls":{"type":"object","properties":{"requested":{"type":"boolean"},"valid":{"type":"boolean"}},"required":["requested","valid"],"additionalProperties":false},"redirects":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"chain":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","minimum":300,"maximum":399},"from":{"type":"string","format":"uri"},"to":{"type":"string","format":"uri"}},"required":["status","from","to"],"additionalProperties":false}}},"required":["count","chain"],"additionalProperties":false},"checked_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"claims":{"minItems":3,"maxItems":4,"type":"array","items":{"type":"object","properties":{"claim":{"type":"string","enum":["reachable","status_matches","https_valid","expected_text_found"]},"passed":{"type":"boolean"},"evidence_paths":{"minItems":1,"maxItems":4,"type":"array","items":{"type":"string"}}},"required":["claim","passed","evidence_paths"],"additionalProperties":false}}},"required":["requested_url","final_url","http","expected_text","tls","redirects","checked_at","claims"],"additionalProperties":false},"checked_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"error":{"type":"string","maxLength":2000}},"required":["verified","checks","evidence","checked_at"],"additionalProperties":false},"example":{"verified":true,"checks":{"reachable":true,"status":200,"https_valid":true,"text_found":true},"evidence":{"requested_url":"https://example.com","final_url":"https://example.com/","http":{"status":200,"expected_status":200,"matched":true},"expected_text":{"value":"Example Domain","checked":true,"matched":true},"tls":{"requested":true,"valid":true},"redirects":{"count":0,"chain":[]},"checked_at":"2026-08-16T08:50:33.986Z","claims":[{"claim":"reachable","passed":true,"evidence_paths":["http.status","final_url"]},{"claim":"status_matches","passed":true,"evidence_paths":["http.status","http.expected_status"]},{"claim":"https_valid","passed":true,"evidence_paths":["tls.requested","tls.valid"]},{"claim":"expected_text_found","passed":true,"evidence_paths":["expected_text.value","expected_text.matched"]}]},"checked_at":"2026-08-16T08:50:33.986Z"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}}}},"408":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}}}}}}},"/v1/tools":{"post":{"summary":"Register a tool (auth required)","tags":["v1-discovery"],"description":"Bearer REGISTRY_ADMIN_TOKEN or provider API key. New providers receive a one-time provider_api_key. Tools stay pending (quarantine) until ownership + verification.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/tools/search":{"get":{"tags":["v1-discovery"],"responses":{"200":{"description":"Default Response"}}}},"/v1/tools/compare":{"get":{"tags":["v1-discovery"],"responses":{"200":{"description":"Default Response"}}}},"/v1/capabilities":{"get":{"tags":["v1-discovery"],"responses":{"200":{"description":"Default Response"}}}},"/v1/metrics/agents":{"get":{"tags":["v1-discovery"],"responses":{"200":{"description":"Default Response"}}}},"/v1/metrics/activation":{"get":{"tags":["v1-discovery"],"responses":{"200":{"description":"Default Response"}}}},"/v1/capabilities/{capability}/tools":{"get":{"tags":["v1-discovery"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"capability","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/graph/capabilities":{"get":{"tags":["v1-discovery"],"responses":{"200":{"description":"Default Response"}}}},"/v1/tools/{idOrSlug}":{"get":{"tags":["v1-discovery"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"idOrSlug","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/tools/{idOrSlug}/trust":{"get":{"tags":["v1-discovery"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"idOrSlug","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/tools/{idOrSlug}/related":{"get":{"tags":["v1-discovery"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"idOrSlug","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/tools/{idOrSlug}/verifications":{"get":{"tags":["v1-discovery"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"idOrSlug","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/tools/{idOrSlug}/verify":{"post":{"tags":["v1-discovery"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"idOrSlug","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/receipts":{"post":{"tags":["v1-discovery"],"responses":{"200":{"description":"Default Response"}}}},"/v1/providers/{slug}":{"get":{"tags":["v1-discovery"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"slug","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/providers/{slug}/ownership/challenge":{"post":{"tags":["v1-discovery"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"slug","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/providers/{slug}/ownership/verify":{"post":{"tags":["v1-discovery"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"slug","required":true}],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://404.directory"}],"tags":[{"name":"tools","description":"First-party executable tools"},{"name":"v1-discovery","description":"Ecosystem registry + discovery. Search is active-only; writes need Bearer admin or provider API key."}]}