{
  "openapi": "3.1.0",
  "info": {
    "title": "Kilowatt API (waitlist live; inference planned)",
    "version": "1.1.0",
    "summary": "Join the Kilowatt early-access waitlist (founding 100).",
    "description": "Early access waitlist. The inference API is not live yet; only the waitlist endpoints work today. Plans: Pro $39/mo, Lite $19/mo (founding pricing, not charged during waitlist). Models: DeepSeek V4.1 Flash-1017. Full docs: https://kilowatt.sh/llms-full.txt",
    "contact": {
      "email": "ops@avatar33.com",
      "url": "https://kilowatt.sh"
    }
  },
  "servers": [
    {
      "url": "https://kilowatt.sh"
    }
  ],
  "paths": {
    "/api/waitlist": {
      "get": {
        "operationId": "getWaitlistStats",
        "summary": "Current waitlist counts",
        "responses": {
          "200": {
            "description": "Counts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Stats"
                }
              }
            }
          }
        },
        "tags": [
          "waitlist"
        ]
      },
      "post": {
        "operationId": "joinWaitlist",
        "summary": "Join the waitlist and get your position",
        "description": "Idempotent per email: re-submitting an email returns its existing position with already_registered=true. Rate limit: 5 new signups per 10 minutes per IP and 20 per /24 network.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JoinRequest"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/JoinRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email was already registered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JoinResponse"
                }
              }
            }
          },
          "201": {
            "description": "Added",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JoinResponse"
                }
              }
            }
          },
          "303": {
            "description": "Form (urlencoded) submissions redirect back to the page with ?joined=<position> or ?error=<message>"
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; see Retry-After header",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "X-Client",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Name of the agent or client making the request (stored)."
          },
          {
            "name": "ref",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Where you found Kilowatt (stored; does not change the result)."
          }
        ],
        "tags": [
          "waitlist"
        ]
      }
    },
    "/models.json": {
      "get": {
        "operationId": "getModels",
        "tags": [
          "data"
        ],
        "summary": "Current model lineup (planned model ids)",
        "responses": {
          "200": {
            "description": "Models",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/plans.json": {
      "get": {
        "operationId": "getPlans",
        "tags": [
          "data"
        ],
        "summary": "Plans, prices and fair-use limits",
        "responses": {
          "200": {
            "description": "Plans",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "get": {
        "operationId": "getMcpInfo",
        "tags": [
          "mcp"
        ],
        "summary": "MCP server description",
        "responses": {
          "200": {
            "description": "Server info",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "mcpJsonRpc",
        "tags": [
          "mcp"
        ],
        "summary": "MCP JSON-RPC 2.0 (streamable HTTP, JSON responses). Tools: join_waitlist, waitlist_status, get_plans, get_models",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "const": "2.0"
                  },
                  "id": {},
                  "method": {
                    "type": "string"
                  },
                  "params": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "202": {
            "description": "Notification accepted"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "JoinRequest": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 254,
            "description": "The human owner's email address."
          },
          "use_case": {
            "type": "string",
            "maxLength": 500
          },
          "agent": {
            "type": "boolean",
            "description": "true when an AI agent submits the request"
          },
          "plan": {
            "type": "string",
            "enum": [
              "pro",
              "lite",
              "undecided"
            ]
          },
          "ref": {
            "type": "string",
            "maxLength": 100,
            "description": "Where you found Kilowatt"
          }
        },
        "example": {
          "email": "owner@example.com",
          "use_case": "coding agent",
          "agent": true,
          "plan": "pro"
        }
      },
      "Stats": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "total_signups": {
            "type": "integer"
          },
          "founding_cap": {
            "type": "integer",
            "const": 100
          },
          "founding_claimed": {
            "type": "integer"
          },
          "founding_spots_left": {
            "type": "integer"
          },
          "waitlist_beyond_founding": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "const": "early_access_waitlist"
          },
          "service_live": {
            "type": "boolean"
          }
        }
      },
      "JoinResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Stats"
          },
          {
            "type": "object",
            "properties": {
              "already_registered": {
                "type": "boolean"
              },
              "position": {
                "type": "integer",
                "minimum": 1
              },
              "founding": {
                "type": "boolean"
              },
              "cohort": {
                "type": "string",
                "enum": [
                  "founding_100",
                  "waitlist"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string"
          },
          "retry_after_seconds": {
            "type": "integer"
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Full docs (markdown)",
    "url": "https://kilowatt.sh/llms-full.txt"
  },
  "tags": [
    {
      "name": "waitlist",
      "description": "Live"
    },
    {
      "name": "data",
      "description": "Live static JSON"
    },
    {
      "name": "mcp",
      "description": "Live MCP server"
    },
    {
      "name": "inference",
      "description": "PLANNED, not live: https://api.kilowatt.sh/v1 (OpenAI-compatible) and https://api.kilowatt.sh (Anthropic-compatible). Not described here until it exists."
    }
  ]
}