{
  "openapi": "3.0.3",
  "info": {
    "title": "L33T API",
    "version": "1.3.37",
    "description": "Proposed Happyleet API contract. Interactive examples are simulated locally; no production API is connected."
  },
  "tags": [
    {
      "name": "Timing"
    },
    {
      "name": "Signals"
    },
    {
      "name": "Infrastructure"
    },
    {
      "name": "Utilities"
    }
  ],
  "paths": {
    "/v1/windows/next": {
      "get": {
        "tags": [
          "Timing"
        ],
        "summary": "Get the next precision window",
        "description": "Returns the next 13:37 delivery window for an IANA timezone. There is no place like 127.0.0.1, but your audience may live elsewhere.",
        "parameters": [
          {
            "name": "timezone",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "Europe/Amsterdam",
                "UTC",
                "America/New_York",
                "Asia/Tokyo"
              ],
              "default": "Europe/Amsterdam"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Example response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "window": {
                      "type": "string"
                    },
                    "timezone": {
                      "type": "string"
                    },
                    "delivery": {
                      "type": "string"
                    },
                    "signal": {
                      "type": "string"
                    },
                    "noise": {
                      "type": "integer"
                    }
                  }
                },
                "example": {
                  "window": "13:37",
                  "timezone": "Europe/Amsterdam",
                  "delivery": "precisely_once",
                  "signal": "all_your_events",
                  "noise": 0
                }
              }
            }
          }
        }
      }
    },
    "/v1/signals/dispatch": {
      "post": {
        "tags": [
          "Signals"
        ],
        "summary": "Queue a targeted business update",
        "description": "Accepts an update for a subscribed technical audience. The example uses a documentation-only destination; no notification is sent.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {
                "audience": "builders",
                "topic": "release.published",
                "message": "A new version is available.",
                "schedule": "next_1337",
                "idempotency_key": "correct-horse-battery-staple"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Example response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "signal_id": {
                      "type": "string"
                    },
                    "ownership": {
                      "type": "string"
                    },
                    "duplicate_count": {
                      "type": "integer"
                    }
                  }
                },
                "example": {
                  "status": "queued",
                  "signal_id": "sig_1337",
                  "ownership": "all_your_events_are_belong_to_you",
                  "duplicate_count": 0
                }
              }
            }
          }
        }
      }
    },
    "/v1/signals/noise": {
      "get": {
        "tags": [
          "Signals"
        ],
        "summary": "Inspect signal quality",
        "description": "Returns an illustrative noise budget for your event stream. Unsolicited packets are quietly shown the door.",
        "responses": {
          "200": {
            "description": "Example response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "signal": {
                      "type": "integer"
                    },
                    "noise": {
                      "type": "integer"
                    },
                    "ratio": {
                      "type": "string"
                    },
                    "unsolicited_packets": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "signal": 1337,
                  "noise": 0,
                  "ratio": "excellent",
                  "unsolicited_packets": "/dev/null"
                }
              }
            }
          }
        }
      }
    },
    "/v1/health": {
      "get": {
        "tags": [
          "Infrastructure"
        ],
        "summary": "Read service health",
        "description": "Example health payload. This preview is not connected to live infrastructure. A healthy system knows the answer; it still checks the logs.",
        "responses": {
          "200": {
            "description": "Example response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "answer": {
                      "type": "integer"
                    },
                    "panic": {
                      "type": "boolean"
                    },
                    "towel": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "status": "operational",
                  "answer": 42,
                  "panic": false,
                  "towel": "available"
                }
              }
            }
          }
        }
      }
    },
    "/v1/handshakes": {
      "post": {
        "tags": [
          "Infrastructure"
        ],
        "summary": "Establish a partner handshake",
        "description": "Demonstrates a three-step partner acknowledgement. A polite SYN deserves a polite SYN-ACK.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {
                "client": "partner-platform",
                "sequence": 1337,
                "flag": "SYN"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Example response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "flag": {
                      "type": "string"
                    },
                    "acknowledgement": {
                      "type": "integer"
                    },
                    "trust": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "flag": "SYN-ACK",
                  "acknowledgement": 1338,
                  "trust": "verify_first"
                }
              }
            }
          }
        }
      }
    },
    "/v1/beverages/brew": {
      "get": {
        "tags": [
          "Utilities"
        ],
        "summary": "Inspect beverage capability",
        "description": "The device supports tea. Coffee requests receive a standards-aware capability response. Some boundaries are worth maintaining.",
        "parameters": [
          {
            "name": "beverage",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "tea",
                "coffee"
              ],
              "default": "tea"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Example response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "beverage": {
                      "type": "string"
                    },
                    "steep_seconds": {
                      "type": "integer"
                    }
                  }
                },
                "example": {
                  "status": "ready",
                  "beverage": "tea",
                  "steep_seconds": 133
                }
              }
            }
          },
          "418": {
            "description": "Requested beverage is not supported by this vessel."
          }
        }
      }
    },
    "/v1/operators/seat": {
      "get": {
        "tags": [
          "Utilities"
        ],
        "summary": "Check operator readiness",
        "description": "Reports the local operator interface state. When diagnostics are inconclusive, check the layer between the keyboard and the chair.",
        "responses": {
          "200": {
            "description": "Example response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "layer": {
                      "type": "integer"
                    },
                    "keyboard": {
                      "type": "string"
                    },
                    "chair": {
                      "type": "string"
                    },
                    "readiness": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "layer": 8,
                  "keyboard": "connected",
                  "chair": "occupied",
                  "readiness": "have_you_tried_turning_it_off_and_on_again"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}