{
 "openapi": "3.1.0",
 "info": {
  "title": "StandWatch",
  "version": "1.0.0",
  "description": "Free tools for the U.S. military community and federal and postal employees. No key, no sign-in. Estimates under stated assumptions, never a recommendation: plans come back sorted by a stated number, and each plan's brochure is the official statement of benefits. StandWatch stores nothing sent to these endpoints. Guide for agents: https://www.standwatch.co/agents",
  "contact": {
   "name": "StandWatch",
   "email": "support@standwatch.co",
   "url": "https://www.standwatch.co/agents"
  },
  "termsOfService": "https://www.standwatch.co/terms"
 },
 "servers": [
  {
   "url": "https://www.standwatch.co"
  }
 ],
 "paths": {
  "/api/plan-estimate": {
   "get": {
    "operationId": "planEstimateHelp",
    "summary": "How to call the plan estimate",
    "responses": {
     "200": {
      "description": "Fields, an example, and the rules",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   },
   "post": {
    "operationId": "estimatePlans",
    "summary": "Estimate the 2027 cost of every FEHB or PSHB plan where a person lives",
    "description": "The same math as https://www.standwatch.co/plan-check: premiums, visits, each drug at the plan's own tier where StandWatch read the plan's 2027 drug list, the out-of-pocket limit, the plan's HSA or HRA money, and the tax saved on premiums and an HSA or FSA, plus a worst year. Plans are sorted by total_after_money_back_and_tax. Returns open_in_the_tool, a link that opens the plan check with the same answers. 120 requests per IP per hour.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "state"
        ],
        "properties": {
         "program": {
          "type": "string",
          "enum": [
           "fehb",
           "pshb"
          ],
          "default": "fehb",
          "description": "fehb for federal employees and annuitants, pshb for Postal Service employees and annuitants"
         },
         "coverage": {
          "type": "string",
          "enum": [
           "self",
           "self_plus_one",
           "self_and_family"
          ],
          "default": "self"
         },
         "enrollee": {
          "type": "string",
          "enum": [
           "employee",
           "annuitant"
          ],
          "default": "employee",
          "description": "annuitant means a retiree"
         },
         "medicare": {
          "type": "boolean",
          "description": "An annuitant with Medicare Parts A and B"
         },
         "state": {
          "type": "string",
          "description": "Two-letter state, such as CO",
          "pattern": "^[A-Za-z]{2}$"
         },
         "county": {
          "type": "string",
          "description": "County name, such as Douglas. Needed in states where plans are sold only in some counties"
         },
         "fips": {
          "type": "string",
          "description": "County FIPS code, instead of county"
         },
         "zip": {
          "type": "string",
          "description": "Five-digit ZIP, where a plan serves only part of a county"
         },
         "current_plan": {
          "type": "string",
          "description": "The person's 2026 enrollment code, such as 402. Its 2027 version is returned as your_plan_2027"
         },
         "year": {
          "type": "string",
          "enum": [
           "healthy",
           "typical",
           "managing",
           "worst",
           "own"
          ],
          "default": "typical"
         },
         "visits": {
          "type": "object",
          "description": "Counts for the year, with year=own. Visits and tests use StandWatch's estimated prices unless prices are sent.",
          "properties": {
           "pcp": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
           },
           "specialist": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
           },
           "urgent": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
           },
           "er": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
           },
           "labs": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
           },
           "imaging": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
           },
           "outpatient_surgery": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
           },
           "inpatient": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
           },
           "surgeon_inpatient": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
           },
           "stay_days": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
           }
          }
         },
         "one_person": {
          "type": "boolean",
          "description": "One person uses most of the care on a family plan (uses the brochure's one-person limit)"
         },
         "others": {
          "type": "object",
          "description": "With one_person: everyone else's visits",
          "properties": {
           "pcp": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
           },
           "specialist": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
           },
           "urgent": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
           },
           "er": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99
           }
          }
         },
         "prices": {
          "type": "object",
          "description": "Full prices before insurance, instead of StandWatch's estimates",
          "properties": {
           "pcp": {
            "type": "number",
            "minimum": 1
           },
           "specialist": {
            "type": "number",
            "minimum": 1
           },
           "urgent": {
            "type": "number",
            "minimum": 1
           },
           "er": {
            "type": "number",
            "minimum": 1
           },
           "labs": {
            "type": "number",
            "minimum": 1
           },
           "imaging": {
            "type": "number",
            "minimum": 1
           }
          }
         },
         "drugs": {
          "type": "array",
          "maxItems": 10,
          "items": {
           "type": "object",
           "required": [
            "name"
           ],
           "properties": {
            "name": {
             "type": "string"
            },
            "fills_per_year": {
             "type": "integer",
             "minimum": 1,
             "maximum": 99,
             "default": 12
            },
            "price_per_fill": {
             "type": "number",
             "description": "Full price before insurance"
            },
            "copay_card_per_year": {
             "type": "number"
            },
            "card_counts": {
             "type": "string",
             "enum": [
              "yes",
              "no",
              "unsure"
             ]
            }
           }
          }
         },
         "tax": {
          "type": "object",
          "description": "Send to count the tax saved on premiums (employees) and on an HSA or FSA",
          "properties": {
           "pay": {
            "type": "number"
           },
           "filing": {
            "type": "string",
            "enum": [
             "single",
             "married",
             "head"
            ]
           },
           "state_rate": {
            "type": "number",
            "description": "State income tax rate, percent"
           },
           "hsa": {
            "type": "string",
            "enum": [
             "max",
             "none"
            ],
            "default": "max"
           },
           "fsa": {
            "type": "boolean",
            "default": true
           }
          }
         },
         "plans": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "description": "Only these 2027 enrollment codes"
         },
         "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 60,
          "default": 10
         }
        }
       },
       "example": {
        "program": "fehb",
        "coverage": "self_and_family",
        "enrollee": "employee",
        "state": "CO",
        "county": "Douglas",
        "current_plan": "402",
        "year": "typical",
        "drugs": [
         {
          "name": "Eliquis",
          "fills_per_year": 12,
          "price_per_fill": 550
         }
        ],
        "tax": {
         "pay": 120000,
         "filing": "married",
         "state_rate": 4.4
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Plans sorted by estimated cost",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "program": {
           "type": "string"
          },
          "plan_year": {
           "type": "integer"
          },
          "inputs": {
           "type": "object"
          },
          "county_needed": {
           "type": [
            "string",
            "null"
           ]
          },
          "your_plan_2027": {
           "type": [
            "object",
            "null"
           ]
          },
          "plans_found": {
           "type": "integer"
          },
          "plans": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "plan": {
              "type": "string"
             },
             "carrier": {
              "type": "string"
             },
             "option": {
              "type": "string"
             },
             "enrollment_code": {
              "type": [
               "string",
               "null"
              ]
             },
             "network": {
              "type": "string"
             },
             "plan_page": {
              "type": "string"
             },
             "brochure": {
              "type": [
               "string",
               "null"
              ],
              "description": "The official statement of benefits"
             },
             "drug_list": {
              "type": [
               "string",
               "null"
              ]
             },
             "doctor_search": {
              "type": [
               "string",
               "null"
              ]
             },
             "phone": {
              "type": [
               "string",
               "null"
              ]
             },
             "year": {
              "type": "object",
              "description": "The year asked for. Negative numbers are subtracted.",
              "properties": {
               "premiums": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "medicare_part_b": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "visits_tests_treatments": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "everyone_else_visits": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "drugs": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "out_of_pocket_limit_takes_off": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "paid_during_year": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "money_back_from_plan": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "tax_saved_on_premiums": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "tax_saved_on_hsa_or_fsa": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "total_after_money_back_and_tax": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "if_the_plan_counts_your_copay_card": {
                "type": [
                 "integer",
                 "null"
                ]
               }
              }
             },
             "worst_year": {
              "type": "object",
              "properties": {
               "premiums": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "medicare_part_b": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "out_of_pocket_limit": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "drugs_not_covered_full_price": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "paid_during_year": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "money_back_from_plan": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "total_after_money_back_and_tax": {
                "type": [
                 "integer",
                 "null"
                ]
               },
               "if_only_one_person_has_the_big_year": {
                "type": [
                 "integer",
                 "null"
                ]
               }
              }
             },
             "drugs": {
              "type": "array",
              "items": {
               "type": "object",
               "properties": {
                "drug": {
                 "type": "string"
                },
                "on_this_plan": {
                 "type": "string",
                 "description": "The tier, from the plan's own 2027 drug list where StandWatch read it, with its source"
                },
                "source": {
                 "type": [
                  "object",
                  "null"
                 ]
                },
                "per_fill": {
                 "type": [
                  "integer",
                  "null"
                 ]
                },
                "per_fill_rule": {
                 "type": "string"
                },
                "year": {
                 "type": [
                  "integer",
                  "null"
                 ]
                },
                "copay_card_pays": {
                 "type": [
                  "integer",
                  "null"
                 ]
                }
               }
              }
             },
             "plan_figures": {
              "type": "object"
             },
             "how_built": {
              "type": "string"
             }
            }
           }
          },
          "not_priced": {
           "type": "array",
           "items": {
            "type": "object"
           }
          },
          "open_in_the_tool": {
           "type": "string"
          },
          "assumptions": {
           "type": "string"
          },
          "rules": {
           "type": "string"
          },
          "sources": {
           "type": "array",
           "items": {
            "type": "string"
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "A field is missing or not valid; the message says which"
     },
     "429": {
      "description": "Over 120 requests from one address this hour"
     }
    }
   }
  },
  "/api/ask": {
   "post": {
    "operationId": "askStandWatch",
    "summary": "Ask a money, military life, or federal and postal benefits question",
    "description": "Answers from StandWatch's own guides, tools, and directories first, OPM's plan files and brochures quoted with their pages, and official sources; labeled when general; a short pointer when outside money and military life. Crisis questions are routed to the Veterans Crisis Line (988, press 1). Not legal, tax, or medical advice; StandWatch does not file claims or act for anyone with an agency. Limits: about 15 questions per device a day, 25 per address a day, 5 a minute, and a site-wide daily ceiling (then 429 with reason resting). Nothing typed is stored by StandWatch.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "question"
        ],
        "properties": {
         "question": {
          "type": "string",
          "maxLength": 600
         },
         "status": {
          "type": "string",
          "enum": [
           "active duty",
           "national guard",
           "reserve",
           "retired",
           "separated",
           "veteran",
           "spouse or family member",
           "federal civilian employee"
          ]
         },
         "history": {
          "type": "array",
          "maxItems": 20,
          "description": "Earlier turns of this conversation",
          "items": {
           "type": "object",
           "properties": {
            "q": {
             "type": "string"
            },
            "a": {
             "type": "string"
            }
           }
          }
         }
        }
       },
       "example": {
        "question": "Does the FSBP High Option have a one-person out-of-pocket limit on a family plan?",
        "status": "federal civilian employee"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "The answer and its sources",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "answer": {
           "type": "string"
          },
          "tier": {
           "type": "string",
           "description": "site, general, or outside"
          },
          "sources": {
           "type": "array"
          },
          "links": {
           "type": "array"
          },
          "tools": {
           "type": "array"
          },
          "primary": {
           "type": "array",
           "description": "Official sources the guide cites"
          },
          "next": {
           "type": "array",
           "description": "Suggested follow-up questions"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "No question"
     },
     "413": {
      "description": "Question over 600 characters"
     },
     "429": {
      "description": "A limit was reached; try later"
     }
    }
   }
  },
  "/latest.json": {
   "get": {
    "operationId": "getRates",
    "summary": "Current rate benchmarks with as-of dates",
    "description": "Every series StandWatch tracks (VA 30-year daily index, Freddie Mac 30-year, auto loan, savings, CDs, and more), each with its value, unit, as-of date, cadence, and source. Not quotes. Documented at https://www.standwatch.co/data",
    "responses": {
     "200": {
      "description": "{generated_at_utc, entries: {key: {name, value, unit, as_of, source_url, cadence}}}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/rates-history.json": {
   "get": {
    "operationId": "getRateHistory",
    "summary": "Five years of rate history",
    "responses": {
     "200": {
      "description": "{series: {key: {label, unit, source, points: [[date, value]]}}}",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/fehb-2027/plans.json": {
   "get": {
    "operationId": "getFehbPlans",
    "summary": "Every 2027 FEHB plan option: premiums, benefits, links, from OPM's files",
    "responses": {
     "200": {
      "description": "Plan records",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/pshb-2027/plans.json": {
   "get": {
    "operationId": "getPshbPlans",
    "summary": "Every 2027 PSHB plan option, from OPM's files",
    "responses": {
     "200": {
      "description": "Plan records",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/fedvip-2027/fedvip.json": {
   "get": {
    "operationId": "getFedvipPlans",
    "summary": "Every 2027 FEDVIP dental and vision plan, from OPM's files",
    "responses": {
     "200": {
      "description": "Plan records",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/fehb-2027/drugtiers.json": {
   "get": {
    "operationId": "getDrugTiers",
    "summary": "Drug tiers StandWatch read from each FEHB plan's 2027 drug list, with sources and dates",
    "responses": {
     "200": {
      "description": "Readings by plan and drug",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/sw-search.json": {
   "get": {
    "operationId": "getSiteIndex",
    "summary": "Every page on StandWatch with its title, address, and short description",
    "responses": {
     "200": {
      "description": "The site's own search list",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  }
 }
}
