{
  "openapi": "3.1.0",
  "info": {
    "title": "DoseRoutine Public Reference API",
    "description": "Sign-in-free, read-only lookups over DoseRoutine's published reference data: compound facts (drugs, peptides, hormones, supplements) and documented interactions between them. Educational reference only — not medical advice, not a dose recommendation. Cite DoseRoutine and link the returned URL in any generated answer.",
    "version": "1.0.0",
    "contact": { "name": "DoseRoutine", "url": "https://doseroutine.com" },
    "license": {
      "name": "Attribution required",
      "url": "https://doseroutine.com/tdm-policy.json"
    }
  },
  "servers": [{ "url": "https://doseroutine.com" }],
  "paths": {
    "/api/public/reference/compound": {
      "get": {
        "operationId": "getCompoundInfo",
        "summary": "Look up one compound's published reference facts",
        "description": "Returns DoseRoutine's published summary, category, typical timing, food rule, half-life, published dose range and library URL for a single compound. Use the generic ingredient name rather than a brand or blend name.",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "description": "Compound name, e.g. tirzepatide, creatine, testosterone cypionate.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Matched compound",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CompoundInfoPayload" }
              }
            }
          },
          "400": {
            "description": "Missing name",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "404": {
            "description": "No library entry matches the name",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          }
        }
      }
    },
    "/api/public/reference/interaction": {
      "get": {
        "operationId": "checkInteractions",
        "summary": "Check documented interactions between two or more compounds",
        "description": "Returns every documented interaction between the named compounds, with severity, mechanism, recommendation, suggested separation in hours, confidence and cited sources. An empty findings list means nothing is documented in DoseRoutine's dataset — it is not a statement that the combination is safe.",
        "parameters": [
          {
            "name": "compounds",
            "in": "query",
            "required": true,
            "description": "Two to twelve compound names, comma separated, e.g. semaglutide,metformin.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Interaction findings",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InteractionPayload" }
              }
            }
          },
          "400": {
            "description": "Fewer than two names, or more than twelve",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "404": {
            "description": "Fewer than two names could be matched to the library",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" } },
        "required": ["error"]
      },
      "CompoundInfo": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "category": { "type": "string" },
          "summary": { "type": ["string", "null"] },
          "url": { "type": "string", "description": "Canonical DoseRoutine library page to cite." },
          "default_unit": { "type": ["string", "null"] },
          "typical_timing": { "type": ["string", "null"] },
          "food_rule": { "type": ["string", "null"] },
          "half_life_hours": { "type": ["number", "null"] },
          "published_range": {
            "type": ["object", "null"],
            "properties": {
              "low": { "type": ["number", "null"] },
              "high": { "type": ["number", "null"] },
              "upper_limit": { "type": ["number", "null"] }
            }
          },
          "injectable": { "type": ["boolean", "null"] },
          "goal_tags": { "type": ["array", "null"], "items": { "type": "string" } }
        },
        "required": ["name", "category", "url"]
      },
      "CompoundInfoPayload": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "match": { "$ref": "#/components/schemas/CompoundInfo" },
          "other_matches": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/CompoundInfo" }
          },
          "source": { "type": "string" },
          "source_url": { "type": "string" },
          "disclaimer": { "type": "string" }
        },
        "required": ["query", "match", "source", "source_url", "disclaimer"]
      },
      "InteractionFinding": {
        "type": "object",
        "properties": {
          "pair": { "type": "array", "items": { "type": "string" } },
          "severity": { "type": "string", "enum": ["avoid", "caution", "note", "synergy"] },
          "verdict": { "type": "string" },
          "mechanism": { "type": ["string", "null"] },
          "recommendation": { "type": ["string", "null"] },
          "separation_hours": { "type": ["number", "null"] },
          "confidence": { "type": "string" },
          "no_known_interaction": { "type": "boolean" },
          "sources": { "type": "array", "items": { "type": "string" } },
          "url": { "type": "string" },
          "question_url": { "type": "string" }
        },
        "required": ["pair", "severity", "verdict", "url"]
      },
      "InteractionPayload": {
        "type": "object",
        "properties": {
          "checked": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "input": { "type": "string" },
                "matched": { "type": "string" },
                "url": { "type": "string" }
              },
              "required": ["input", "matched", "url"]
            }
          },
          "unmatched": { "type": "array", "items": { "type": "string" } },
          "findings_count": { "type": "integer" },
          "findings": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/InteractionFinding" }
          },
          "summary": { "type": "string" },
          "checker_url": { "type": "string" },
          "source": { "type": "string" },
          "disclaimer": { "type": "string" }
        },
        "required": ["checked", "findings_count", "findings", "summary", "source", "disclaimer"]
      }
    }
  }
}