{
  "openapi": "3.1.0",
  "info": {
    "title": "Broomed Web Companion API",
    "version": "1.0.0",
    "description": "API specification for Broomed desktop app license management, device activations, and AI gateway proxy."
  },
  "servers": [
    {
      "url": "https://broomed.app",
      "description": "Production Server"
    },
    {
      "url": "http://localhost:4321",
      "description": "Local Development Server"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "description": "Returns current server status and timestamp.",
        "responses": {
          "200": {
            "description": "Server is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "ts": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/broomed-pubkey": {
      "get": {
        "summary": "Public Key for License Entitlement Verification",
        "description": "Returns PEM-encoded public key used by desktop clients to cryptographically verify offline entitlement tokens.",
        "responses": {
          "200": {
            "description": "PEM-encoded RSA public key",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "-----BEGIN PUBLIC KEY-----\n..."
                }
              }
            }
          },
          "404": {
            "description": "Public key not configured"
          }
        }
      }
    },
    "/api/v1/license/activate": {
      "post": {
        "summary": "Activate Desktop Device",
        "description": "Redeems an activation code to register a client device and obtain a signed entitlement session token.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "activation_code",
                  "device_public_key"
                ],
                "properties": {
                  "activation_code": {
                    "type": "string",
                    "example": "A9X7K-B32RT-Q8L9P"
                  },
                  "device_public_key": {
                    "type": "string",
                    "example": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5..."
                  },
                  "platform": {
                    "type": "string",
                    "example": "darwin"
                  },
                  "app_version": {
                    "type": "string",
                    "example": "1.0.0"
                  },
                  "fingerprint": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Device successfully activated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "activated"
                    },
                    "license": {
                      "type": "object",
                      "properties": {
                        "session": {
                          "type": "string",
                          "description": "Signed JWT entitlement token"
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "subscription_period_end": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "device_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid payload format"
          },
          "403": {
            "description": "Subscription expired or inactive"
          },
          "404": {
            "description": "Activation code not found"
          },
          "409": {
            "description": "Activation code consumed or device limit reached"
          },
          "410": {
            "description": "Activation code expired"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/api/v1/license/refresh": {
      "post": {
        "summary": "Refresh Entitlement Token",
        "description": "Refreshes an active entitlement JWT before it expires (7 days duration).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Token refreshed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "refreshed"
                    },
                    "license": {
                      "type": "object",
                      "properties": {
                        "session": {
                          "type": "string"
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "subscription_period_end": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid entitlement token"
          },
          "403": {
            "description": "Device revoked or subscription expired"
          }
        }
      }
    },
    "/api/v1/license/device/deactivate": {
      "post": {
        "summary": "Deactivate Device",
        "description": "Revokes an active device registration and invalidates existing license sessions.",
        "security": [
          {
            "CookieAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "device_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Device deactivated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "deactivated"
                    },
                    "device_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "No active device found"
          }
        }
      }
    },
    "/api/v1/ai/text": {
      "post": {
        "summary": "AI Text Gateway",
        "description": "Proxies text generation queries via Gemini / Groq / OpenRouter with quota guard.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "prompt"
                ],
                "properties": {
                  "prompt": {
                    "type": "string",
                    "maxLength": 100000,
                    "example": "Summarize this log output"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Text inference output",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string",
                      "example": "groq"
                    },
                    "model": {
                      "type": "string",
                      "example": "llama-3.1-8b-instant"
                    },
                    "output": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Subscription expired"
          },
          "413": {
            "description": "Payload exceeds size limit"
          },
          "429": {
            "description": "Rate limit / quota exceeded"
          }
        }
      }
    },
    "/api/v1/ai/vision": {
      "post": {
        "summary": "AI Vision Gateway",
        "description": "Processes image understanding and OCR tasks on images up to 5MB.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "image"
                ],
                "properties": {
                  "prompt": {
                    "type": "string",
                    "default": "describe this image"
                  },
                  "image": {
                    "type": "string",
                    "description": "Base64 encoded image"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Vision inference output",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string"
                    },
                    "model": {
                      "type": "string"
                    },
                    "output": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/billing/checkout": {
      "post": {
        "summary": "Create Checkout Session",
        "description": "Generates a Dodo Payments subscription checkout session URL for authenticated users.",
        "security": [
          {
            "CookieAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "plan": {
                    "type": "string",
                    "enum": [
                      "monthly",
                      "yearly"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout session URL",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/billing/portal": {
      "post": {
        "summary": "Create Customer Portal Session",
        "description": "Generates a link to the Dodo Payments customer portal for subscription management.",
        "security": [
          {
            "CookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Customer portal session URL",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "CookieAuth": {
        "type": "apiKey",
        "in": "cookie",
        "name": "sb-access-token"
      }
    }
  }
}