{"openapi":"3.1.1","info":{"title":"tld.wiki Agent API","version":"1.0.0","description":"Public read-only domain research. REST and MCP share operations. No purchases or account actions."},"servers":[{"url":"https://agent.tld.wiki"}],"security":[],"paths":{"/v1/lookup_metrics":{"post":{"operationId":"lookup_metrics","summary":"Read domain lookup history by real searches or idle scheduled probes, cached/fresh and availability/premium; includes sample counts and unresolved outcomes. Reading does not run checks.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"period":{"default":"24h","type":"string","enum":["24h","7d","30d"]},"origin":{"default":"all","type":"string","enum":["all","real","probe"]}},"required":["period","origin"],"additionalProperties":false}}}},"responses":{"200":{"description":"Public operation result; ambiguous and partial are explicit result states","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"202":{"description":"Lookup pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Explicit operation failure (400)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"403":{"description":"Explicit operation failure (403)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Explicit operation failure (404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"410":{"description":"Explicit operation failure (410)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"413":{"description":"Explicit operation failure (413)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"422":{"description":"Explicit operation failure (422)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"429":{"description":"Explicit operation failure (429)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"503":{"description":"Explicit operation failure (503)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}}}}},"/v1/capabilities":{"post":{"operationId":"capabilities","summary":"Discover supported entities, operations, limits and limitations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Public operation result; ambiguous and partial are explicit result states","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"202":{"description":"Lookup pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Explicit operation failure (400)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"403":{"description":"Explicit operation failure (403)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Explicit operation failure (404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"410":{"description":"Explicit operation failure (410)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"413":{"description":"Explicit operation failure (413)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"422":{"description":"Explicit operation failure (422)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"429":{"description":"Explicit operation failure (429)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"503":{"description":"Explicit operation failure (503)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}}}}},"/v1/explore":{"post":{"operationId":"explore","summary":"Start here: identify a pasted input or reference, search a product area, or browse capabilities. Ambiguity requires an explicit choice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"input":{"type":"string","minLength":1,"maxLength":1024},"ref":{"type":"object","properties":{"type":{"type":"string","enum":["catalog","tld","registrar","category","registrar_tld","domain","search_label","lookup","backlink","promotion","research","comparison","dataset"]},"id":{"type":"string","minLength":1,"maxLength":300}},"required":["type","id"],"additionalProperties":false},"area":{"type":"string","enum":["tlds","registrars","categories","idn","launches","backlinks","promotions","benefits","payment_methods","currencies","contributions","research","datasets","comparisons","lookup_metrics"]},"limit":{"default":10,"type":"integer","minimum":1,"maximum":25},"cursor":{"type":"string","minLength":1,"maxLength":6000}},"required":["limit"],"additionalProperties":false,"allOf":[{"not":{"required":["ref","input"]}},{"not":{"required":["ref","area"]}}]}}}},"responses":{"200":{"description":"Public operation result; ambiguous and partial are explicit result states","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"202":{"description":"Lookup pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Explicit operation failure (400)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"403":{"description":"Explicit operation failure (403)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Explicit operation failure (404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"410":{"description":"Explicit operation failure (410)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"413":{"description":"Explicit operation failure (413)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"422":{"description":"Explicit operation failure (422)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"429":{"description":"Explicit operation failure (429)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"503":{"description":"Explicit operation failure (503)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}}}}},"/v1/entity":{"post":{"operationId":"entity","summary":"Open a returned entity reference and discover applicable relationships.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ref":{"type":"object","properties":{"type":{"type":"string","enum":["catalog","tld","registrar","category","registrar_tld","domain","search_label","lookup","backlink","promotion","research","comparison","dataset"]},"id":{"type":"string","minLength":1,"maxLength":300}},"required":["type","id"],"additionalProperties":false}},"required":["ref"],"additionalProperties":false}}}},"responses":{"200":{"description":"Public operation result; ambiguous and partial are explicit result states","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"202":{"description":"Lookup pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Explicit operation failure (400)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"403":{"description":"Explicit operation failure (403)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Explicit operation failure (404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"410":{"description":"Explicit operation failure (410)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"413":{"description":"Explicit operation failure (413)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"422":{"description":"Explicit operation failure (422)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"429":{"description":"Explicit operation failure (429)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"503":{"description":"Explicit operation failure (503)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}}}}},"/v1/follow":{"post":{"operationId":"follow","summary":"Replay a returned relationship call, preserving its reference, filters and cursor.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ref":{"type":"object","properties":{"type":{"type":"string","enum":["catalog","tld","registrar","category","registrar_tld","domain","search_label","lookup","backlink","promotion","research","comparison","dataset"]},"id":{"type":"string","minLength":1,"maxLength":300}},"required":["type","id"],"additionalProperties":false},"relation":{"type":"string","enum":["extensions","registrars","categories","idn","launches","sellers","technical","services","sublevels","history","features","sources","prices","availability","registration","results","backlinks","related","brand_kit","promotions","benefits","payment_methods","currencies","community","revisions","contributions","research","datasets","observations","comparisons","lookup_metrics"]},"filters":{"type":"object","properties":{"query":{"type":"string","maxLength":100},"category":{"type":"string","maxLength":80},"registrar":{"type":"string","maxLength":100},"registrars":{"type":"string","maxLength":4096,"pattern":"^[a-z0-9][a-z0-9._-]{0,99}(?:,[a-z0-9][a-z0-9._-]{0,99})*$"},"exclude_registrars":{"type":"string","maxLength":4096,"pattern":"^[a-z0-9][a-z0-9._-]{0,99}(?:,[a-z0-9][a-z0-9._-]{0,99})*$"},"payment_methods":{"type":"string","maxLength":4096,"pattern":"^[a-z0-9][a-z0-9._-]{0,99}(?:,[a-z0-9][a-z0-9._-]{0,99})*$"},"payment_match":{"type":"string","enum":["any","all"]},"include_promotions":{"type":"boolean"},"include_benefits":{"type":"boolean"},"display_currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","NZD","JPY","KRW","CNY","INR","BRL","MXN","TRY","IDR","SGD","CHF"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"sort":{"type":"string","enum":["suffix","popularity","character_count","registration","renewal","transfer","three_year","name","supported_suffixes","priced_suffixes","category","checked_at","value"]},"order":{"type":"string","enum":["asc","desc"]},"idn":{"type":"boolean"},"feature":{"type":"string","enum":["whois_privacy","dnssec"]},"supported":{"type":"string","enum":["true","false","unknown"]},"scope":{"type":"string","enum":["general","suffix"]},"suffix":{"type":"string","maxLength":253},"operation":{"type":"string","enum":["all","register","renew","transfer"]},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"price_mode":{"type":"string","enum":["advertised","verified"]},"fresh_only":{"type":"boolean"},"free":{"type":"string","enum":["true","false","unknown"]},"reciprocal":{"type":"string","enum":["true","false","unknown"]},"verification":{"type":"string","enum":["verified","partial","unavailable"]},"publicly_registrable":{"type":"string","enum":["true","false","unknown"]},"state":{"type":"string","enum":["active","upcoming","expired","unverified"]}},"additionalProperties":false},"limit":{"default":10,"type":"integer","minimum":1,"maximum":25},"cursor":{"type":"string","minLength":1,"maxLength":6000}},"required":["ref","relation","limit"],"additionalProperties":false}}}},"responses":{"200":{"description":"Public operation result; ambiguous and partial are explicit result states","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"202":{"description":"Lookup pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Explicit operation failure (400)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"403":{"description":"Explicit operation failure (403)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Explicit operation failure (404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"410":{"description":"Explicit operation failure (410)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"413":{"description":"Explicit operation failure (413)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"422":{"description":"Explicit operation failure (422)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"429":{"description":"Explicit operation failure (429)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"503":{"description":"Explicit operation failure (503)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}}}}},"/v1/check":{"post":{"operationId":"check","summary":"Explicitly query availability and premium classification for 1–10 registrable domains using product-owned automatic routing. Does not buy or modify domains.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"domains":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":253}}},"required":["domains"],"additionalProperties":false}}}},"responses":{"200":{"description":"Public operation result; ambiguous and partial are explicit result states","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"202":{"description":"Lookup pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Explicit operation failure (400)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"403":{"description":"Explicit operation failure (403)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Explicit operation failure (404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"410":{"description":"Explicit operation failure (410)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"413":{"description":"Explicit operation failure (413)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"422":{"description":"Explicit operation failure (422)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"429":{"description":"Explicit operation failure (429)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"503":{"description":"Explicit operation failure (503)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}}}}},"/v1/lookup":{"post":{"operationId":"lookup","summary":"Poll or paginate an existing lookup; availability and premium progress independently.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"limit":{"default":10,"type":"integer","minimum":1,"maximum":25},"cursor":{"type":"string","minLength":1,"maxLength":6000}},"required":["id","limit"],"additionalProperties":false}}}},"responses":{"200":{"description":"Public operation result; ambiguous and partial are explicit result states","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"202":{"description":"Lookup pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Explicit operation failure (400)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"403":{"description":"Explicit operation failure (403)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Explicit operation failure (404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"410":{"description":"Explicit operation failure (410)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"413":{"description":"Explicit operation failure (413)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"422":{"description":"Explicit operation failure (422)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"429":{"description":"Explicit operation failure (429)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"503":{"description":"Explicit operation failure (503)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}}}}},"/llms.txt":{"get":{"summary":"Agent discovery document","responses":{"200":{"description":"Discovery document","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/skill.md":{"get":{"summary":"Agent discovery document","responses":{"200":{"description":"Discovery document","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/openapi.json":{"get":{"summary":"Agent discovery document","responses":{"200":{"description":"Discovery document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/":{"get":{"summary":"Service entry point","responses":{"200":{"description":"Discovery links and executable start call"}}}},"/mcp":{"post":{"summary":"Official MCP Streamable HTTP transport","description":"Supports modern discovery and legacy stateless initialization. Use an official MCP client; REST operation arguments are exposed as tool arguments.","responses":{"200":{"description":"MCP result as application/json or text/event-stream"},"202":{"description":"Accepted notification"},"400":{"description":"MCP protocol or schema error"},"403":{"description":"Origin/Host rejected"},"429":{"description":"Shared request budget reached"}}},"get":{"responses":{"405":{"description":"Persistent SSE subscriptions are not offered"}}},"delete":{"responses":{"405":{"description":"Stateless transport has no session to delete"}}}},"/v1/tools":{"get":{"operationId":"tool_catalog","summary":"Machine-readable operation and capability catalog","responses":{"200":{"description":"Operation names, input JSON Schemas and REST/MCP mappings","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/health/live":{"get":{"operationId":"liveness","responses":{"200":{"description":"Service alive / product API ready"},"503":{"description":"Product API unavailable"}}}},"/health/ready":{"get":{"operationId":"readiness","responses":{"200":{"description":"Service alive / product API ready"},"503":{"description":"Product API unavailable"}}}}},"components":{"schemas":{"Call":{"type":"object","additionalProperties":false,"required":["operation","params"],"properties":{"operation":{"type":"string","enum":["lookup_metrics","capabilities","explore","entity","follow","check","lookup"]},"params":{"type":"object","additionalProperties":true}}},"Node":{"type":"object","required":["ref","label","product_url","open_call"],"properties":{"ref":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"type":"string","enum":["catalog","tld","registrar","category","registrar_tld","domain","search_label","lookup","backlink","promotion","research","comparison","dataset"]},"id":{"type":"string","minLength":1,"maxLength":300}},"required":["type","id"],"additionalProperties":false},"label":{"type":"string"},"product_url":{"type":"string","format":"uri"},"open_call":{"type":"object","additionalProperties":false,"required":["operation","params"],"properties":{"operation":{"type":"string","enum":["lookup_metrics","capabilities","explore","entity","follow","check","lookup"]},"params":{"type":"object","additionalProperties":true}}},"data":{}}},"Result":{"type":"object","required":["status","operation","fetched_at","nodes","relations","pagination","issues"],"properties":{"status":{"type":"string","enum":["ok","pending","partial","ambiguous","unavailable","unsupported","not_found","invalid_input","rate_limited","expired","forbidden"]},"operation":{"type":"string"},"fetched_at":{"type":"string","format":"date-time"},"entity":{"$ref":"#/components/schemas/Node"},"data":{"description":"Native authoritative product payload. Exact numeric strings, source metadata, context and domain-specific states are retained."},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/Node"}},"relations":{"type":"array","items":{"type":"object","required":["name","description","follow_call"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"follow_call":{"type":"object","additionalProperties":false,"required":["operation","params"],"properties":{"operation":{"type":"string","enum":["lookup_metrics","capabilities","explore","entity","follow","check","lookup"]},"params":{"type":"object","additionalProperties":true}}}}}},"pagination":{"type":"object","required":["next_call"],"properties":{"next_call":{"anyOf":[{"type":"object","additionalProperties":false,"required":["operation","params"],"properties":{"operation":{"type":"string","enum":["lookup_metrics","capabilities","explore","entity","follow","check","lookup"]},"params":{"type":"object","additionalProperties":true}}},{"type":"null"}]}},"additionalProperties":true},"issues":{"type":"array","items":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}},"capabilities":{"type":"object","additionalProperties":true},"restart_call":{"type":"object","additionalProperties":false,"required":["operation","params"],"properties":{"operation":{"type":"string","enum":["lookup_metrics","capabilities","explore","entity","follow","check","lookup"]},"params":{"type":"object","additionalProperties":true}}},"poll_call":{"type":"object","additionalProperties":false,"required":["operation","params"],"properties":{"operation":{"type":"string","enum":["lookup_metrics","capabilities","explore","entity","follow","check","lookup"]},"params":{"type":"object","additionalProperties":true}}},"retry_after_ms":{"type":"integer"}}}}}}