AvailabilityBatch

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cheapest-domains/json-schema/cheapest-domains-availability-batch-schema.json",
  "title": "AvailabilityBatch",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cheapest-domains-openapi.json#/components/schemas/AvailabilityBatch",
  "type": "object",
  "required": [
    "apiVersion",
    "service",
    "results",
    "unconfirmedDomains",
    "cachedOnly"
  ],
  "properties": {
    "apiVersion": {
      "type": "string"
    },
    "service": {
      "$ref": "#/$defs/ServiceInformation"
    },
    "cachedOnly": {
      "type": "boolean"
    },
    "results": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "$ref": "#/$defs/AvailabilityEvidence"
      }
    },
    "unconfirmedDomains": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string"
      },
      "description": "Domains with unknown availability, not taken domains. Premium must be inspected separately even when this list is empty."
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "retryAfterSeconds"
      ],
      "description": "Partial failure: retain successful facts and wait before another explicit request. A confirmed Cloudflare-specific rate denial may continue through admitted fallback providers. Caller or shared-storage failure with no returned results uses the ordinary HTTP/MCP error envelope.",
      "properties": {
        "code": {
          "type": "string"
        },
        "retryAfterSeconds": {
          "type": "number",
          "minimum": 0
        },
        "domains": {
          "type": "array",
          "maxItems": 20,
          "items": {
            "type": "string"
          },
          "description": "When present, only these domains have a paused fallback."
        }
      }
    }
  },
  "$defs": {
    "AvailabilityAttempt": {
      "type": "object",
      "required": [
        "provider",
        "availability",
        "premium",
        "reason",
        "checkedAt",
        "expiresAt"
      ],
      "properties": {
        "provider": {
          "type": "object",
          "required": [
            "id",
            "name",
            "documentation"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "documentation": {
              "type": "string",
              "format": "uri"
            }
          }
        },
        "availability": {
          "enum": [
            "available",
            "unavailable",
            "unknown"
          ]
        },
        "premium": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "reason": {
          "type": "string"
        },
        "checkedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "expiresAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "outcome": {
          "enum": [
            "answered",
            "failed",
            "pending"
          ],
          "description": "Whether this stage returned an answer, failed before confirming evidence, or is still in progress. Optional for older responses."
        },
        "retryAfterSeconds": {
          "type": "number",
          "minimum": 0,
          "description": "Suggested wait after a failed stage; never an evidence lifetime."
        }
      }
    },
    "AvailabilityEvidence": {
      "type": "object",
      "required": [
        "domain",
        "status",
        "reason",
        "message",
        "provider",
        "checkedAt",
        "expiresAt"
      ],
      "properties": {
        "availability": {
          "enum": [
            "available",
            "unavailable",
            "unknown"
          ],
          "description": "Registration status; independent of premium classification."
        },
        "premium": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Null means not confirmed, never standard tier."
        },
        "registrar": {
          "type": "string"
        },
        "attempts": {
          "type": "array",
          "maxItems": 5,
          "items": {
            "$ref": "#/$defs/AvailabilityAttempt"
          }
        },
        "fallback": {
          "type": "object",
          "required": [
            "registrar",
            "state",
            "reason"
          ],
          "properties": {
            "registrar": {
              "type": "string"
            },
            "state": {
              "enum": [
                "used",
                "unavailable"
              ]
            },
            "reason": {
              "type": "string"
            }
          }
        },
        "domain": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "available",
            "unavailable",
            "premium",
            "unsupported",
            "unknown"
          ]
        },
        "reason": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "provider": {
          "type": "object",
          "required": [
            "id",
            "name",
            "documentation"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "documentation": {
              "type": "string",
              "format": "uri"
            }
          }
        },
        "checkedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Successful provider response time; null when no reliable result was obtained."
        },
        "expiresAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Recheck after this time; never a reservation or guarantee until expiry."
        },
        "listEnrichmentComplete": {
          "type": "boolean",
          "description": "Batch results: true when availability is known or every configured fallback stage has answered for this name. False means a later explicit request may add facts; it never means taken."
        }
      }
    },
    "ServiceInformation": {
      "type": "object",
      "required": [
        "name",
        "url",
        "setupUrl",
        "pluginUrl"
      ],
      "description": "Cheapest Domains identity and optional setup links, separate from upstream evidence. Does not establish client installation or provider health.",
      "properties": {
        "name": {
          "const": "Cheapest Domains"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "setupUrl": {
          "type": "string",
          "format": "uri"
        },
        "pluginUrl": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  }
}