{
  "openapi": "3.0.3",
  "info": {
    "title": "tmgmt Hosting Management API",
    "version": "0.0.0",
    "description": "Read-only management surface for the ThatMgmt hosting reseller layer. Every route is read-only (POST exists only for dry-run previews). Bearer-authenticated routes fail closed without wired auth/composition. Generated from src/route-registry.ts — do not edit by hand."
  },
  "servers": [
    {
      "url": "http://127.0.0.1:8787",
      "description": "Dev/fixture default (HOSTING_HTTP_HOST/PORT)"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "paths": {
    "/health/live": {
      "get": {
        "summary": "Liveness probe. No authentication required.",
        "operationId": "gethealth_live",
        "tags": [
          "platform",
          "composition:health"
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "404": {
            "description": "Unknown route."
          }
        }
      }
    },
    "/health/ready": {
      "get": {
        "summary": "Readiness probe. No authentication required.",
        "operationId": "gethealth_ready",
        "tags": [
          "platform",
          "composition:health"
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "404": {
            "description": "Unknown route."
          }
        }
      }
    },
    "/v1/capabilities": {
      "get": {
        "summary": "Machine-readable capability inventory for the authenticated tenant: the dynamic discovery endpoint.",
        "operationId": "getv1_capabilities",
        "tags": [
          "platform",
          "composition:management"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/operations/{operationId}": {
      "get": {
        "summary": "Inspect a tracked operation by id.",
        "operationId": "getv1_operations_operationId",
        "tags": [
          "operations",
          "composition:management"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "operationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "includeAudit",
            "in": "query",
            "required": false,
            "description": "Set to 1/true/yes to include the audit trail.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "auditLimit",
            "in": "query",
            "required": false,
            "description": "Positive integer cap on audit entries returned.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/domains": {
      "get": {
        "summary": "List tenant domain resources (paginated).",
        "operationId": "getv1_domains",
        "tags": [
          "domains",
          "composition:management"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "pageSize",
            "in": "query",
            "required": false,
            "description": "Positive integer page size.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pageToken",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/domains/{resourceId}": {
      "get": {
        "summary": "Inspect a single domain resource by server-side resource id.",
        "operationId": "getv1_domains_resourceId",
        "tags": [
          "domains",
          "composition:management"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "resourceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/domains/{resourceId}/dns": {
      "get": {
        "summary": "Inspect DNS records for a domain resource.",
        "operationId": "getv1_domains_resourceId_dns",
        "tags": [
          "dns",
          "composition:management"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "resourceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Record type filter, e.g. A, CNAME.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Record name filter.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Positive integer page number.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "required": false,
            "description": "Positive integer page size.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/domains/{resourceId}/dns/preview": {
      "post": {
        "summary": "Dry-run preview of a DNS changeset. Read-only: never mutates live DNS.",
        "operationId": "postv1_domains_resourceId_dns_preview",
        "tags": [
          "dns",
          "composition:management"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "resourceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "JSON body with changeSet and options (see dns.previewChange).",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/context": {
      "get": {
        "summary": "Trusted reseller customer context derived server-side for the tenant.",
        "operationId": "getv1_portfolio_context",
        "tags": [
          "customer-accounts",
          "composition:portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/diagnostics": {
      "get": {
        "summary": "Operator diagnostics for supplier catalog entitlements (no raw supplier payloads).",
        "operationId": "getv1_portfolio_diagnostics",
        "tags": [
          "portfolio",
          "composition:portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/health": {
      "get": {
        "summary": "Domain portfolio health summary.",
        "operationId": "getv1_portfolio_health",
        "tags": [
          "portfolio",
          "composition:portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio": {
      "get": {
        "summary": "Domain portfolio listing for the trusted reseller context.",
        "operationId": "getv1_portfolio",
        "tags": [
          "portfolio",
          "composition:portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/renewal-risk": {
      "get": {
        "summary": "Renewal-risk view over the domain portfolio.",
        "operationId": "getv1_portfolio_renewal_risk",
        "tags": [
          "portfolio",
          "composition:portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/actions": {
      "get": {
        "summary": "Available portfolio actions for the trusted context (read-only listing).",
        "operationId": "getv1_portfolio_actions",
        "tags": [
          "portfolio",
          "composition:portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/notifications": {
      "get": {
        "summary": "Portfolio notifications for the trusted context.",
        "operationId": "getv1_portfolio_notifications",
        "tags": [
          "notifications",
          "composition:portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/notifications/schemas/{schemaName}": {
      "get": {
        "summary": "JSON schema for a named notification payload.",
        "operationId": "getv1_portfolio_notifications_schemas_schemaName",
        "tags": [
          "notifications",
          "composition:portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "schemaName",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/domains/availability": {
      "get": {
        "summary": "Check domain availability via the supplier (read-only).",
        "operationId": "getv1_domains_availability",
        "tags": [
          "domains",
          "composition:portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "Fully qualified domain name to check.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "optimizeFor",
            "in": "query",
            "required": false,
            "description": "SPEED or ACCURACY.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/domains/suggestions": {
      "get": {
        "summary": "Suggest alternative domains for a query (read-only).",
        "operationId": "getv1_domains_suggestions",
        "tags": [
          "domains",
          "composition:portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "Search query.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "required": false,
            "description": "Positive integer page size.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tlds",
            "in": "query",
            "required": false,
            "description": "Comma-separated TLD filter.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/domains/quote": {
      "get": {
        "summary": "Quote a registration without purchasing. Provider quote tokens are never returned.",
        "operationId": "getv1_domains_quote",
        "tags": [
          "domains",
          "composition:portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "Fully qualified domain name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "period",
            "in": "query",
            "required": false,
            "description": "Registration period in years (default 1).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/domains/prepare-registration": {
      "get": {
        "summary": "Prepare (never execute) a registration: returns the safety-checked plan only.",
        "operationId": "getv1_domains_prepare_registration",
        "tags": [
          "domains",
          "composition:portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "Fully qualified domain name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "period",
            "in": "query",
            "required": false,
            "description": "Registration period in years (default 1).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/catalog": {
      "get": {
        "summary": "Supplier API catalog status: documented families, probe state, and required scopes.",
        "operationId": "getv1_portfolio_catalog",
        "tags": [
          "catalog",
          "composition:catalog"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/certificates": {
      "get": {
        "summary": "Certificate inventory for the trusted customer. 409 when the certificates category is unverified.",
        "operationId": "getv1_portfolio_certificates",
        "tags": [
          "ssl-certificates",
          "composition:broader-portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/commerce": {
      "get": {
        "summary": "Commerce store/channel/transaction reads for the trusted customer. 409 when unverified.",
        "operationId": "getv1_portfolio_commerce",
        "tags": [
          "commerce",
          "composition:broader-portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/broader-health": {
      "get": {
        "summary": "Consolidated broader-product health: certificate expiration/status/renewal risk plus Commerce health and exceptions. Supplier reads are restricted server-side to entitled categories; derived evidence only — raw supplier payloads stay internal.",
        "operationId": "getv1_portfolio_broader_health",
        "tags": [
          "portfolio",
          "composition:broader-portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/exceptions": {
      "get": {
        "summary": "Prioritized read-only operator/AI exception queue derived from entitled portfolio health; supplier payloads remain internal.",
        "operationId": "getv1_portfolio_exceptions",
        "tags": [
          "portfolio",
          "composition:broader-portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "405": {
            "description": "Method not allowed. The exception queue is GET-only; no response body.",
            "headers": {
              "Allow": {
                "description": "Supported methods.",
                "schema": {
                  "type": "string",
                  "example": "GET"
                }
              }
            }
          },
          "409": {
            "description": "Portfolio category not verified. No entitled categories for the trusted customer (certificates, commerce); the body is the standard error envelope with code \"ApprovalRequired\".",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "example": "ApprovalRequired"
                    },
                    "message": {
                      "type": "string",
                      "example": "Portfolio category is not verified"
                    },
                    "retryable": {
                      "type": "boolean",
                      "example": false
                    },
                    "details": {
                      "type": "object",
                      "example": {
                        "reason": "portfolio_category_unverified"
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/offerings": {
      "get": {
        "summary": "Reseller offering coverage matrix: every documented supplier family, its exposed routes, entitlement state, and write-gating.",
        "operationId": "getv1_offerings",
        "tags": [
          "offerings",
          "composition:offerings"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/aftermarket": {
      "get": {
        "summary": "Aftermarket/auction reads for the trusted customer. 409 when the auctions category is unverified.",
        "operationId": "getv1_portfolio_aftermarket",
        "tags": [
          "aftermarket",
          "composition:extended-portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/parking": {
      "get": {
        "summary": "Parked-domain reads for the trusted customer. 409 when the parking category is unverified.",
        "operationId": "getv1_portfolio_parking",
        "tags": [
          "parking",
          "composition:extended-portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    },
    "/v1/portfolio/hosting": {
      "get": {
        "summary": "Hosting-product reads for the trusted customer. 409 when the hosting category is unverified.",
        "operationId": "getv1_portfolio_hosting",
        "tags": [
          "hosting",
          "composition:extended-portfolio"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope varies per route; see README)."
          },
          "401": {
            "description": "Missing or invalid bearer credential."
          },
          "404": {
            "description": "Unknown route."
          },
          "503": {
            "description": "Route composition not wired (auth or deps missing)."
          }
        }
      }
    }
  }
}