{
  "openapi": "3.1.0",
  "info": {
    "title": "tld.expert API",
    "version": "1.0.0",
    "description": "Public domain-availability and TLD-intelligence API for tld.expert. Check whether a domain is registrable, get a per-domain verdict, and follow registrar buy-links when a name is available. The same data is exposed as a public MCP server (streamable HTTP, no auth) at https://tld.expert/mcp with tools check_domain_availability, suggest_tld_alternatives, get_tld_prices and explain_tld.",
    "contact": {
      "name": "tld.expert",
      "url": "https://tld.expert"
    }
  },
  "servers": [
    {
      "url": "https://tld.expert",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/check": {
      "get": {
        "operationId": "checkDomainAvailability",
        "summary": "Check domain availability",
        "description": "Given a full domain (e.g. \"acme.io\") or a bare name (e.g. \"acme\", which is expanded across candidate TLDs), returns a per-domain availability verdict with optional price and registrar buy-links.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "A full domain (\"acme.io\") or a bare second-level name (\"acme\").",
            "schema": {
              "type": "string",
              "examples": [
                "acme.io",
                "acme"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Availability result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "checkDomainAvailabilityBatch",
        "summary": "Check domain availability (batch/body)",
        "description": "Same verdict semantics as GET, accepting the domain or bare name in a JSON body. Supports checking one name across multiple TLDs.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "Full domain or bare name."
                  },
                  "tlds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Optional TLDs to expand a bare name across (e.g. [\"com\",\"io\",\"ai\"])."
                  }
                },
                "required": [
                  "domain"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Availability result(s).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Verdict": {
        "type": "string",
        "description": "Per-domain availability verdict. \"taken\" = registered; \"available\" = registrable now; \"premium\" = available at a premium price; \"likely\" = probably available (heuristic, not authoritative); \"unknown\" = could not be determined.",
        "enum": [
          "taken",
          "available",
          "premium",
          "unknown",
          "likely"
        ]
      },
      "DomainResult": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "description": "The evaluated domain."
          },
          "verdict": {
            "$ref": "#/components/schemas/Verdict"
          },
          "price": {
            "type": "number",
            "nullable": true,
            "description": "Registration price in USD, when known."
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "examples": [
              "USD"
            ]
          },
          "registrars": {
            "type": "array",
            "description": "Registrar buy-links, when the domain is registrable.",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "price": {
                  "type": "number",
                  "nullable": true
                }
              }
            }
          }
        },
        "required": [
          "domain",
          "verdict"
        ]
      },
      "CheckResponse": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DomainResult"
            }
          }
        },
        "required": [
          "results"
        ]
      }
    }
  }
}