{
  "openapi": "3.1.0",
  "info": {
    "title": "Whohouse CDN Response Foundry",
    "version": "1.0.0",
    "description": "Deploy valid, unusual, or deliberately malformed wire responses to stable wildcard HTTPS hosts. Every deployment creates a preserved immutable revision; replacing a route changes only its current pointer."
  },
  "servers": [{"url": "https://cdn.whohouse.io"}],
  "security": [{"bearerAuth": []}],
  "paths": {
    "/v1/hosts": {
      "post": {
        "summary": "Generate or validate a host label",
        "parameters": [{"name": "host", "in": "query", "schema": {"type": "string"}}],
        "responses": {"200": {"description": "Host details", "content": {"application/json": {"schema": {"type": "object"}}}}}
      }
    },
    "/v1/deploy": {
      "post": {
        "summary": "Deploy a structured or base64-encoded exact response",
        "description": "Use status/reason/headers/body for a convenient response, first_line for a nonstandard first line, or wire_base64 for fully exact bytes.",
        "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Deployment"}}}},
        "responses": {
          "201": {"$ref": "#/components/responses/Deployed"},
          "400": {"$ref": "#/components/responses/Error"},
          "401": {"$ref": "#/components/responses/Error"},
          "409": {"$ref": "#/components/responses/Error"}
        }
      },
      "put": {
        "summary": "Deploy a structured response",
        "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Deployment"}}}},
        "responses": {"201": {"$ref": "#/components/responses/Deployed"}}
      }
    },
    "/v1/file": {
      "put": {
        "summary": "Serve the request body as a file with easy defaults",
        "parameters": [
          {"$ref": "#/components/parameters/Host"},
          {"$ref": "#/components/parameters/Path"},
          {"$ref": "#/components/parameters/Method"},
          {"$ref": "#/components/parameters/Agent"},
          {"$ref": "#/components/parameters/Replace"},
          {"name": "status", "in": "query", "schema": {"type": "integer", "minimum": 100, "maximum": 999, "default": 200}},
          {"name": "reason", "in": "query", "schema": {"type": "string"}},
          {"name": "content_type", "in": "query", "schema": {"type": "string"}}
        ],
        "description": "The payload can be binary and may be streamed. X-Whohouse-First-Line overrides the generated first line. X-Whohouse-Response-Headers accepts unpadded base64url JSON containing an object or [name,value] pairs.",
        "requestBody": {"required": true, "content": {"application/octet-stream": {"schema": {"type": "string", "contentEncoding": "binary"}}}},
        "responses": {"201": {"$ref": "#/components/responses/Deployed"}}
      }
    },
    "/v1/raw": {
      "put": {
        "summary": "Deploy exact wire bytes",
        "description": "The request body becomes the complete public response, byte-for-byte. No HTTP status line, headers, separator, or validity is required.",
        "parameters": [
          {"$ref": "#/components/parameters/Host"},
          {"$ref": "#/components/parameters/Path"},
          {"$ref": "#/components/parameters/Method"},
          {"$ref": "#/components/parameters/Agent"},
          {"$ref": "#/components/parameters/Replace"}
        ],
        "requestBody": {"required": true, "content": {"application/octet-stream": {"schema": {"type": "string", "contentEncoding": "binary"}}}},
        "responses": {"201": {"$ref": "#/components/responses/Deployed"}}
      }
    },
    "/v1/routes": {
      "get": {
        "summary": "List current route pointers",
        "parameters": [{"$ref": "#/components/parameters/Cursor"}, {"$ref": "#/components/parameters/Limit"}],
        "responses": {"200": {"$ref": "#/components/responses/List"}}
      }
    },
    "/v1/revisions": {
      "get": {
        "summary": "List every preserved revision",
        "parameters": [{"$ref": "#/components/parameters/Cursor"}, {"$ref": "#/components/parameters/Limit"}],
        "responses": {"200": {"$ref": "#/components/responses/List"}}
      }
    },
    "/v1/revisions/{revision_id}": {
      "get": {
        "summary": "Get revision metadata",
        "parameters": [{"name": "revision_id", "in": "path", "required": true, "schema": {"type": "string"}}],
        "responses": {"200": {"description": "Revision metadata", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Record"}}}}}
      }
    },
    "/v1/revisions/{revision_id}/wire": {
      "get": {
        "summary": "Download a revision's exact stored wire bytes",
        "parameters": [{"name": "revision_id", "in": "path", "required": true, "schema": {"type": "string"}}],
        "responses": {"200": {"description": "Exact bytes, wrapped as an authenticated control-plane download", "content": {"application/octet-stream": {"schema": {"type": "string", "contentEncoding": "binary"}}}}}
      }
    },
    "/v1/agents": {
      "get": {
        "summary": "List per-agent deployment and delivery statistics",
        "parameters": [{"$ref": "#/components/parameters/Cursor"}, {"$ref": "#/components/parameters/Limit"}],
        "responses": {"200": {"$ref": "#/components/responses/List"}}
      }
    },
    "/v1/admin/overview": {
      "get": {
        "summary": "Load aggregate console statistics and recent activity",
        "responses": {"200": {"description": "Dashboard data", "content": {"application/json": {"schema": {"type": "object"}}}}}
      }
    }
  },
  "components": {
    "securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer"}},
    "parameters": {
      "Host": {"name": "host", "in": "query", "description": "One label or full direct subdomain. Omit for a generated host.", "schema": {"type": "string"}},
      "Path": {"name": "path", "in": "query", "required": true, "schema": {"type": "string", "default": "/"}},
      "Method": {"name": "method", "in": "query", "schema": {"type": "string", "default": "*"}},
      "Agent": {"name": "agent", "in": "query", "schema": {"type": "string", "default": "anonymous"}},
      "Replace": {"name": "replace", "in": "query", "schema": {"type": "boolean", "default": true}},
      "Cursor": {"name": "cursor", "in": "query", "schema": {"type": "string"}},
      "Limit": {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 500, "default": 100}}
    },
    "schemas": {
      "Deployment": {
        "type": "object",
        "properties": {
          "host": {"type": "string", "description": "Omit or use an empty string to generate a host."},
          "path": {"type": "string", "default": "/"},
          "method": {"type": "string", "default": "*"},
          "agent": {"type": "string", "default": "anonymous"},
          "replace": {"type": "boolean", "default": true},
          "status": {"type": "integer", "minimum": 100, "maximum": 999, "default": 200},
          "reason": {"type": "string"},
          "version": {"type": "string", "default": "HTTP/1.1"},
          "first_line": {"type": "string", "description": "Overrides version/status/reason."},
          "headers": {
            "description": "Either an object whose values are strings/string arrays, or an array of [name,value] pairs. Arrays preserve duplicates and order.",
            "oneOf": [{"type": "object", "additionalProperties": {"oneOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]}}, {"type": "array", "items": {"type": "array", "prefixItems": [{"type": "string"}, {"type": "string"}], "minItems": 2, "maxItems": 2}}]
          },
          "auto_headers": {"type": "boolean", "default": true},
          "content_type": {"type": "string"},
          "body": {"type": "string"},
          "body_base64": {"type": "string", "contentEncoding": "base64"},
          "wire": {"type": "string", "description": "Complete response bytes represented as UTF-8 text."},
          "wire_base64": {"type": "string", "contentEncoding": "base64", "description": "Complete exact response bytes."}
        }
      },
      "Record": {
        "type": "object",
        "properties": {
          "kind": {"type": "string"},
          "revision_id": {"type": "string"},
          "host": {"type": "string"},
          "path": {"type": "string"},
          "method": {"type": "string"},
          "agent": {"type": "string"},
          "mode": {"type": "string"},
          "status_hint": {"type": "string"},
          "content_type": {"type": "string"},
          "url": {"type": "string", "format": "uri"},
          "created_at": {"type": "string", "format": "date-time"},
          "updated_at": {"type": "string", "format": "date-time"},
          "payload_bytes": {"type": "integer"},
          "response_bytes": {"type": "integer"},
          "requests": {"type": "integer"},
          "bytes_served": {"type": "integer"}
        }
      }
    },
    "responses": {
      "Deployed": {
        "description": "The immutable revision was stored and its route is live.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "ok": {"type": "boolean"},
                "url": {"type": "string", "format": "uri"},
                "revision_id": {"type": "string"}
              }
            }
          }
        }
      },
      "List": {
        "description": "A newest-first page.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "items": {"type": "array", "items": {"$ref": "#/components/schemas/Record"}},
                "next_cursor": {"type": "string"}
              }
            }
          }
        }
      },
      "Error": {
        "description": "Error response",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {"type": "string"},
                "message": {"type": "string"}
              }
            }
          }
        }
      }
    }
  }
}