{
  "openapi": "3.1.0",
  "info": {
    "title": "EveryCard Rx pricing API",
    "version": "2026-11-06",
    "description": "Every way to pay for a prescription, ranked by what the patient pays. Each option carries its source and the time it was checked. No fee changes the order; tied options go nearest pharmacy first."
  },
  "servers": [
    {
      "url": "https://everycardrx.com"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "param": {
                "type": "string"
              },
              "candidates": {
                "type": "array"
              }
            }
          }
        }
      },
      "Option": {
        "type": "object",
        "description": "One way to pay. Amounts are integer cents.",
        "properties": {
          "id": {
            "type": "string"
          },
          "rank": {
            "type": "integer"
          },
          "kind": {
            "type": "string",
            "enum": [
              "discount_card",
              "mail_order",
              "membership_plan",
              "generic_list",
              "manufacturer_direct",
              "copay_card",
              "insurance_copay"
            ]
          },
          "title": {
            "type": "string"
          },
          "where": {
            "type": "string"
          },
          "totalCents": {
            "type": "integer",
            "description": "What the patient pays, shipping and any required membership included."
          },
          "priceCents": {
            "type": "integer"
          },
          "shippingCents": {
            "type": "integer"
          },
          "regularCents": {
            "type": "integer"
          },
          "distanceMiles": {
            "type": "number"
          },
          "isMailOrder": {
            "type": "boolean"
          },
          "howToUse": {
            "type": "string"
          },
          "caveats": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "url": {
            "type": "string"
          },
          "endsOn": {
            "type": "string",
            "format": "date"
          },
          "isDemo": {
            "type": "boolean",
            "description": "Simulated price (demo builds only). Never true in production."
          },
          "source": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "checkedAt": {
                "type": "string",
                "format": "date-time"
              },
              "url": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/v1/price": {
      "get": {
        "summary": "Rank every way to pay for one prescription",
        "parameters": [
          {
            "name": "drug",
            "in": "query",
            "required": true,
            "description": "Name with strength (\"atorvastatin 20 mg\") or a key from /v1/drugs.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "zip",
            "in": "query",
            "required": true,
            "description": "5-digit US ZIP code.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{5}$"
            }
          },
          {
            "name": "coverage",
            "in": "query",
            "required": true,
            "description": "The patient's coverage. Copay cards are shown only for commercial; drug-maker offers apply their own exclusions.",
            "schema": {
              "type": "string",
              "enum": [
                "commercial",
                "medicare",
                "medicaid",
                "military_va",
                "none",
                "not_sure"
              ]
            }
          },
          {
            "name": "quantity",
            "in": "query",
            "required": false,
            "description": "Units; defaults to a typical month.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            }
          },
          {
            "name": "days_supply",
            "in": "query",
            "required": false,
            "description": "Days the fill lasts.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365
            }
          },
          {
            "name": "prime",
            "in": "query",
            "required": false,
            "description": "1 if the patient has Amazon Prime (RxPass needs it).",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            }
          },
          {
            "name": "copay",
            "in": "query",
            "required": false,
            "description": "The patient's insurance copay in dollars, to compare against.",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "medicare_plan",
            "in": "query",
            "required": false,
            "description": "Medicare only: plan ID (S4802-083) or key (S4802_083_0). Adds the plan's estimated cost, phase-aware, from CMS plan files.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ytd_out_of_pocket",
            "in": "query",
            "required": false,
            "description": "Medicare only: dollars paid for covered drugs so far this year.",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "extra_help",
            "in": "query",
            "required": false,
            "description": "Medicare only: 1 if the patient has Extra Help.",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked options, best first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "price"
                    },
                    "best": {
                      "$ref": "#/components/schemas/Option"
                    },
                    "options": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Option"
                      }
                    },
                    "savings": {
                      "type": "object"
                    },
                    "benchmark": {
                      "type": "object"
                    },
                    "advice": {
                      "type": "array"
                    },
                    "stats": {
                      "type": "object"
                    },
                    "checkedAt": {
                      "type": "string"
                    },
                    "isDemo": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No product matches.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Ambiguous: pick a candidate key and ask again. We never guess a strength.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/list": {
      "post": {
        "summary": "Price a whole medication list: one pharmacy versus a split",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "drugs",
                  "zip",
                  "coverage"
                ],
                "properties": {
                  "drugs": {
                    "type": "array",
                    "minItems": 2,
                    "maxItems": 15,
                    "items": {
                      "type": "string"
                    }
                  },
                  "zip": {
                    "type": "string"
                  },
                  "coverage": {
                    "type": "string",
                    "enum": [
                      "commercial",
                      "medicare",
                      "medicaid",
                      "military_va",
                      "none",
                      "not_sure"
                    ]
                  },
                  "prime": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The cheapest single place and the cheapest split, shipping counted once"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/programs": {
      "get": {
        "summary": "Screen for savings programs (Extra Help, Medicare Savings Programs, insulin cap, drug-maker assistance)",
        "parameters": [
          {
            "name": "coverage",
            "in": "query",
            "required": true,
            "description": "The patient's coverage. Copay cards are shown only for commercial; drug-maker offers apply their own exclusions.",
            "schema": {
              "type": "string",
              "enum": [
                "commercial",
                "medicare",
                "medicaid",
                "military_va",
                "none",
                "not_sure"
              ]
            }
          },
          {
            "name": "zip",
            "in": "query",
            "required": false,
            "description": "5-digit US ZIP code.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{5}$"
            }
          },
          {
            "name": "household_size",
            "in": "query",
            "required": false,
            "description": "People in the household.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "yearly_income",
            "in": "query",
            "required": false,
            "description": "Household income in dollars.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "savings_under_limit",
            "in": "query",
            "required": false,
            "description": "true if savings are under the program limit.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "drugs",
            "in": "query",
            "required": false,
            "description": "Comma-separated medications.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Each program: may_qualify, need_info or unlikely, with why and how to apply"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/drugs": {
      "get": {
        "summary": "Search the catalog (RxNorm-keyed products)",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Any name: generic, brand or alias, with or without strength.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching products"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/medicare/plans": {
      "get": {
        "summary": "Find a Medicare Part D or Medicare Advantage drug plan in CMS's plan files, by plan ID or name",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Plan ID (S4802-083) or name words.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Two-letter state to narrow a name search.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plans, with the key to pass as medicare_plan"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/foundations": {
      "get": {
        "summary": "Charitable foundation disease funds (status read live from the foundation's site when a diagnosis is given) and state drug programs",
        "parameters": [
          {
            "name": "diagnosis",
            "in": "query",
            "required": false,
            "description": "Condition to match, e.g. multiple myeloma or MS; omit for all funds.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Two-letter state for state programs (drug assistance, insulin caps, HIV drug programs).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Funds and state programs"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/copay": {
      "get": {
        "summary": "The copay assistance database: every drug-maker copay card, rebate, free trial and bridge program we've checked, by brand, each with its source",
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": false,
            "description": "Brand or generic name to search; omit for all.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Copay programs"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/offers": {
      "get": {
        "summary": "The curated drug-maker offers and copay cards, with sources and review dates",
        "responses": {
          "200": {
            "description": "Offers"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sources": {
      "get": {
        "summary": "Every data source, its method and freshness (no key needed)",
        "security": [],
        "responses": {
          "200": {
            "description": "Sources"
          }
        }
      }
    }
  }
}