{"openapi":"3.1.0","info":{"title":"suffix.agency API","version":"1.0.0","description":"Free agent-first HTTP API for comparing registrar domain prices,\nchecking availability (including premiums), and obtaining executable\npurchase plans. Domains register into the end user's own registrar\naccount; suffix.agency is not a registrar or reseller.\n\nStart with https://suffix.agency/llms.txt\n","contact":{"url":"https://suffix.agency","name":"suffix.agency"}},"servers":[{"url":"https://suffix.agency/v1","description":"Production"}],"paths":{"/registrars":{"get":{"summary":"List registrars and purchase capabilities","operationId":"listRegistrars","responses":{"200":{"description":"Registrar matrix","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"registrars":{"type":"array","items":{"$ref":"#/components/schemas/RegistrarSummary"}}}}}}}}}},"/registrars/{slug}":{"get":{"summary":"Registrar detail","operationId":"getRegistrar","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Registrar detail"},"404":{"$ref":"#/components/responses/Error"}}}},"/prices":{"get":{"summary":"Standard list prices for a TLD","operationId":"getPrices","parameters":[{"name":"tld","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List prices"},"503":{"$ref":"#/components/responses/Error"}}}},"/compare":{"get":{"summary":"Rank registrar offers for a domain's TLD","operationId":"compare","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"}},{"name":"optimize","in":"query","schema":{"type":"string","enum":["register","tco_2y","renew","year1"],"default":"register"}},{"name":"live_quote","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Ranked offers"}}}},"/availability":{"post":{"summary":"Batch definitive availability","operationId":"checkAvailability","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domains"],"properties":{"domains":{"type":"array","maxItems":10,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Per-domain definitive statuses"},"429":{"$ref":"#/components/responses/Error"}}}},"/quote":{"post":{"summary":"Live registrar quotes (premium-aware)","operationId":"quote","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string"},"registrars":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Quotes"}}}},"/purchase-plan":{"post":{"summary":"Cold-start executable purchase plan","description":"Returns prerequisites the agent must have (email, card, contact, …)\nplus ordered steps that create or log into a registrar account,\nverify email, add payment, and complete the purchase.\nSteps may branch with `when` (for example `account.exists == false`).\n","operationId":"purchasePlan","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchasePlanRequest"}}}},"responses":{"200":{"description":"Purchase plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchasePlanResponse"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/suggest":{"post":{"summary":"Suggest candidate domains","operationId":"suggest","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"}},"tlds":{"type":"array","items":{"type":"string"}},"max_register_cents":{"type":"integer"}}}}}},"responses":{"200":{"description":"Candidates"}}}},"/health":{"get":{"summary":"Service health","operationId":"health","responses":{"200":{"description":"Healthy"},"503":{"description":"Unhealthy"}}}}},"components":{"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"schemas":{"ErrorBody":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retry_after_s":{"type":"integer"}}}}},"RegistrarSummary":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"adapter_maturity":{"type":"string","enum":["healthy","degraded","path_closed"],"description":"healthy = purchase-plan available; degraded = temporarily unavailable;\npath_closed = adapter exhaustively proven unavailable (terminal)\n"},"requires_sms":{"type":"boolean"},"requires_kyc":{"type":"boolean"},"auth_modes":{"type":"array","items":{"type":"string"}},"payment_modes":{"type":"array","items":{"type":"string"}}}},"Prerequisite":{"type":"object","required":["id","label","description","required"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"}}},"PlanStep":{"type":"object","required":["id","title","action"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"action":{"type":"string","enum":["http","browser","email.wait","payment.ensure","secret.store","secret.load","assert"]},"when":{"type":"string","description":"Optional branch predicate, e.g. account.exists == false"},"request":{"type":"object","additionalProperties":true},"expect":{"type":"object","additionalProperties":true},"on_fail":{"type":"string"}}},"PurchasePlanRequest":{"type":"object","required":["domain","registrar"],"properties":{"domain":{"type":"string"},"registrar":{"type":"string"},"optimize":{"type":"string","enum":["register","tco_2y","renew","year1"],"default":"register"},"accept_premium":{"type":"boolean","default":false},"accept_price_cents":{"type":"integer","nullable":true},"max_price_cents":{"type":"integer","nullable":true},"years":{"type":"integer","default":1},"agent_capabilities":{"type":"array","items":{"type":"string","enum":["http","email","payment","browser","secrets","sms"]}}}},"PurchasePlanResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":"string","enum":["ready","needs_capability","needs_confirmation","unsupported","adapter_unhealthy"]},"domain":{"type":"string"},"registrar":{"type":"string"},"prerequisites":{"type":"array","items":{"$ref":"#/components/schemas/Prerequisite"}},"steps":{"type":"array","items":{"$ref":"#/components/schemas/PlanStep"}},"risks":{"type":"array","items":{"type":"string"}},"agreements":{"type":"array","items":{"type":"object","additionalProperties":true}},"missing_capabilities":{"type":"array","items":{"type":"string"}},"validation":{"type":"object","description":"How far this plan has been proven. Agents must read this before buying.","properties":{"level":{"type":"string","enum":["template_unverified","documented_api_mock_tested","harness_mock_executed"]},"live_register_proven":{"type":"boolean"},"notes":{"type":"string"}}}}}}}}