{
  "openapi": "3.0.3",
  "info": {
    "title": "GlucIQ Fasting Service API",
    "description": "Intermittent fasting tracking microservice for GlucIQ platform",
    "version": "1.0.0",
    "contact": { "name": "GlucIQ", "url": "https://gluciq.com" }
  },
  "servers": [
    { "url": "https://fasting.api.gluciq.com", "description": "Production" },
    { "url": "http://localhost:8080", "description": "Local Development" }
  ],
  "paths": {
    "/api/v1/sessions/start": {
      "post": {
        "tags": ["Sessions"],
        "summary": "Start a fasting session",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "startedAt": { "type": "string", "format": "date-time" },
                  "goalHours": {
                    "type": "number",
                    "default": 16,
                    "description": "Target fasting duration in hours. Common protocol values include 12, 14, 16, 18, 20, 23, 24, 36, 48, and 72."
                  }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Session started" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/sessions/{id}/end": {
      "put": {
        "tags": ["Sessions"],
        "summary": "End a fasting session",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "endedAt": { "type": "string", "format": "date-time" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Session ended" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/sessions/active": {
      "get": {
        "tags": ["Sessions"],
        "summary": "Get active fasting session",
        "responses": { "200": { "description": "Active session" }, "404": { "description": "No active session" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/sessions/active/insights": {
      "get": {
        "tags": ["Sessions"],
        "summary": "Get active session insights",
        "description": "Computes elapsed progress, current metabolic stage, next milestone, and goal ETA for the current fast.",
        "responses": { "200": { "description": "Active session insights" }, "404": { "description": "No active session" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/sessions": {
      "get": {
        "tags": ["Sessions"],
        "summary": "List fasting sessions",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": { "200": { "description": "Paginated sessions" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/sessions/{id}": {
      "get": {
        "tags": ["Sessions"],
        "summary": "Get session by ID",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Session detail" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      },
      "put": {
        "tags": ["Sessions"],
        "summary": "Update session",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Session updated" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      },
      "delete": {
        "tags": ["Sessions"],
        "summary": "Delete session",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "204": { "description": "Session deleted" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/plans": {
      "get": {
        "tags": ["Plans"],
        "summary": "List fasting plans",
        "description": "Returns the built-in fasting protocol catalog used for onboarding, plan switching, and recommendations, including extended protocols (24h, 36h, 48h, 72h).",
        "responses": { "200": { "description": "Plan catalog" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/plans/recommended": {
      "get": {
        "tags": ["Plans"],
        "summary": "Get recommended fasting plan",
        "description": "Returns a recommended plan and alternatives using goal, streak, and historical adherence heuristics.",
        "responses": { "200": { "description": "Recommended plan" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/fasting/context": {
      "get": {
        "tags": ["Plans"],
        "summary": "Get fasting context",
        "description": "Returns active fasting context including protocol key, elapsed minutes, and metabolic stage at an optional reference time.",
        "parameters": [
          { "name": "at", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Optional RFC3339 timestamp. Defaults to now." }
        ],
        "responses": { "200": { "description": "Fasting context" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/goals": {
      "get": {
        "tags": ["Goals"],
        "summary": "Get user fasting goals",
        "responses": { "200": { "description": "User goals" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      },
      "put": {
        "tags": ["Goals"],
        "summary": "Create or update fasting goals",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["defaultGoalHours"],
                "properties": {
                  "defaultGoalHours": { "type": "number", "minimum": 1, "maximum": 168 },
                  "eatingWindowStart": { "type": "string", "example": "12:00:00" },
                  "eatingWindowEnd": { "type": "string", "example": "20:00:00" },
                  "activeDays": { "type": "array", "items": { "type": "integer" }, "example": [1,2,3,4,5,6,7] },
                  "unitPreference": { "type": "string", "enum": ["metric", "imperial"] },
                  "reminderStart": { "type": "boolean" },
                  "reminderEnd": { "type": "boolean" },
                  "reminderStreak": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Goals updated" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/streaks": {
      "get": {
        "tags": ["Streaks"],
        "summary": "Get user streak data",
        "responses": { "200": { "description": "Streak data" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/challenges": {
      "get": {
        "tags": ["Challenges"],
        "summary": "List challenges with user progress",
        "responses": { "200": { "description": "Challenges with progress" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/challenges/{id}": {
      "get": {
        "tags": ["Challenges"],
        "summary": "Get challenge detail with progress",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Challenge detail" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/weight": {
      "post": {
        "tags": ["Weight"],
        "summary": "Log weight measurement",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["weightKg"],
                "properties": {
                  "weightKg": { "type": "number", "minimum": 0.1, "example": 85.5 },
                  "measuredAt": { "type": "string", "format": "date-time" },
                  "notes": { "type": "string" },
                  "relatedSessionId": { "type": "string", "format": "uuid" }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Weight logged" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      },
      "get": {
        "tags": ["Weight"],
        "summary": "List weight history",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": { "200": { "description": "Weight history" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/weight/{id}": {
      "put": {
        "tags": ["Weight"],
        "summary": "Update weight log",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "weightKg": { "type": "number" },
                  "measuredAt": { "type": "string", "format": "date-time" },
                  "notes": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Weight updated" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      },
      "delete": {
        "tags": ["Weight"],
        "summary": "Delete weight log",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "204": { "description": "Weight deleted" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/stats": {
      "get": {
        "tags": ["Stats"],
        "summary": "Get lifetime fasting statistics",
        "responses": { "200": { "description": "Lifetime stats" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/stats/recent": {
      "get": {
        "tags": ["Stats"],
        "summary": "Get last 7 days activity",
        "responses": { "200": { "description": "Recent activity" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/stats/trends": {
      "get": {
        "tags": ["Stats"],
        "summary": "Get fasting trends",
        "parameters": [{ "name": "period", "in": "query", "schema": { "type": "string", "enum": ["7d","30d","90d","1y"], "default": "30d" } }],
        "responses": { "200": { "description": "Trend data" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/coach/daily-brief": {
      "get": {
        "tags": ["Coach"],
        "summary": "Get coaching brief",
        "description": "Generates a coaching brief with provider selection, strict JSON output, heuristic fallback, and a recommended plan.",
        "responses": { "200": { "description": "Coaching brief" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/api/v1/coach/history": {
      "get": {
        "tags": ["Coach"],
        "summary": "Get coaching brief history",
        "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } }],
        "responses": { "200": { "description": "Coaching brief history" } },
        "security": [{ "bearerAuth": [] }, { "devAuth": [] }]
      }
    },
    "/health": {
      "get": {
        "tags": ["Health"],
        "summary": "Health check",
        "responses": { "200": { "description": "Service healthy" } }
      }
    },
    "/health/live": {
      "get": {
        "tags": ["Health"],
        "summary": "Liveness probe",
        "responses": { "200": { "description": "Service alive" } }
      }
    },
    "/health/ready": {
      "get": {
        "tags": ["Health"],
        "summary": "Readiness probe",
        "responses": { "200": { "description": "Service ready" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "devAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Auth-User-ID",
        "description": "Development only - pass a UUID directly"
      }
    }
  }
}