{
  "openapi": "3.1.0",
  "info": {
    "title": "DomainShark API",
    "version": "1.0.0",
    "summary": "Lowest-friction Australian (.au) domain availability, discovery and registration hand-off.",
    "description": "Free demo tier (no API key). Australian (.au) specialist covering com.au, net.au, org.au, id.au, asn.au and au. Rate limited to 5 domain records per minute per IP. Registration completes via a checkout hand-off to Dingoblue (auDA-accredited); automated pre-funded registration is on the roadmap. See https://www.domainshark.com.au/llms-full.txt.",
    "contact": { "name": "DomainShark", "url": "https://www.domainshark.com.au/contact" },
    "termsOfService": "https://www.domainshark.com.au/terms"
  },
  "servers": [ { "url": "https://api.domainshark.com.au", "description": "Production" } ],
  "paths": {
    "/v1/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Dataset stats",
        "description": "Public counters for the available .au drop dataset.",
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stats" } } }
          }
        }
      }
    },
    "/v1/domains/check": {
      "get": {
        "operationId": "checkDomain",
        "summary": "Check .au domain availability",
        "description": "Live availability for one registrable .au domain plus dataset enrichment and a registration hand-off URL when available.",
        "parameters": [
          {
            "name": "domain", "in": "query", "required": true,
            "description": "Fully qualified .au domain, e.g. example.com.au",
            "schema": { "type": "string", "example": "example.com.au" }
          }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResult" } } } },
          "400": { "description": "Invalid or missing domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Rate limited", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the budget resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/suggest": {
      "get": {
        "operationId": "suggestDomains",
        "summary": "Suggest aged available .au domains",
        "description": "Available .au domains ranked by Wayback score (highest first). Optional keyword pattern and minimum score.",
        "parameters": [
          { "name": "q", "in": "query", "required": false, "description": "Keyword to match in the name ([a-z0-9-], max 64).", "schema": { "type": "string", "example": "coffee" } },
          { "name": "mode", "in": "query", "required": false, "description": "How q matches the name.", "schema": { "type": "string", "enum": ["contains", "prefix", "suffix"], "default": "contains" } },
          { "name": "min_wayback", "in": "query", "required": false, "description": "Minimum Wayback score.", "schema": { "type": "integer", "minimum": 0, "default": 0 } },
          { "name": "tld", "in": "query", "required": false, "description": "Restrict to one .au TLD.", "schema": { "type": "string", "enum": ["com.au", "net.au", "org.au", "id.au", "asn.au", "au"] } },
          { "name": "limit", "in": "query", "required": false, "description": "Max results (capped by the free-tier budget).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResult" } } } },
          "429": { "description": "Rate limited", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Stats": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "available_records": { "type": "integer" },
          "tlds": { "type": "array", "items": { "type": "string" } },
          "refreshed": { "type": ["string", "null"] },
          "note": { "type": "string" }
        }
      },
      "Domain": {
        "type": "object",
        "properties": {
          "domain": { "type": "string" },
          "tld": { "type": "string" },
          "length": { "type": "integer" },
          "wayback": { "type": "integer", "description": "Wayback/archive activity score; higher = more established." },
          "first_seen": { "type": ["string", "null"], "description": "First date this drop record was seen (YYYY-MM-DD)." },
          "available": { "type": "boolean" },
          "register_url": { "type": ["string", "null"], "description": "Checkout hand-off to the auDA-accredited registrar." },
          "detail_url": { "type": "string" },
          "wayback_url": { "type": "string" }
        }
      },
      "CheckResult": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "domain": { "type": "string" },
          "tld": { "type": "string" },
          "known": { "type": "boolean", "description": "Whether the name is in the DomainShark dataset." },
          "hidden": { "type": "boolean" },
          "registered": { "type": "boolean" },
          "available": { "type": "boolean" },
          "length": { "type": "integer" },
          "wayback": { "type": "integer" },
          "first_seen": { "type": ["string", "null"] },
          "register_url": { "type": ["string", "null"] },
          "detail_url": { "type": "string" },
          "wayback_url": { "type": "string" },
          "rate": { "$ref": "#/components/schemas/Rate" }
        }
      },
      "SuggestResult": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "query": { "type": "string" },
          "mode": { "type": "string" },
          "min_wayback": { "type": "integer" },
          "tld": { "type": "string" },
          "count": { "type": "integer" },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } },
          "timed_out": { "type": "boolean", "description": "Present and true when the pattern was too broad to rank within the time cap." },
          "note": { "type": "string" },
          "rate": { "$ref": "#/components/schemas/Rate" }
        }
      },
      "Rate": {
        "type": "object",
        "properties": {
          "limit_per_min": { "type": "integer" },
          "remaining": { "type": "integer" },
          "reset_in": { "type": "integer", "description": "Seconds until the per-minute budget resets." }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "request_id": { "type": "string" }
            }
          }
        }
      }
    }
  }
}