{
  "openapi": "3.1.0",
  "info": {
    "title": "Hypeless API",
    "version": "1.0.0",
    "description": "Indian stock market news from named outlets, story pages and a rule-based Tip Checker. Headlines, short descriptions and our own summaries only, never full articles, never buy/sell/hold advice. Educational: Hypeless is not registered with SEBI. The first 50 calls a day per account are free, then Rs 0.50 a call (the Ask endpoint is Rs 2) from prepaid credit.",
    "contact": { "email": "support@hypeless.in", "url": "https://hypeless.in/developers" }
  },
  "servers": [{ "url": "https://hypeless.in/api/v1" }],
  "security": [{ "bearer": [] }],
  "components": {
    "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A key from https://hypeless.in/developers, like hl_live_..." } },
    "schemas": {
      "Error": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "enum": ["missing_or_bad_key", "invalid_key", "out_of_credits", "plan_has_no_ai", "daily_limit", "daily_ai_limit", "unavailable", "not_configured"] }, "message": { "type": "string" } } }
    },
    "responses": {
      "Error": { "description": "An error with an error name you can test for (401, 402, 403, 429 or 503).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  },
  "paths": {
    "/news": {
      "get": {
        "summary": "Latest stories",
        "description": "Latest Indian market stories from named outlets, with the outlets that covered each, links and the saved Quick read.",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Company name to search for" },
          { "name": "category", "in": "query", "schema": { "type": "string", "enum": ["markets", "companies", "ipos", "economy", "banking", "commodities", "funds", "global", "tech", "auto", "pharma", "energy"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } },
          { "name": "summary", "in": "query", "schema": { "type": "string", "enum": ["1"] }, "description": "1 adds today's short market summary" }
        ],
        "responses": { "200": { "description": "A list of stories." }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/story/{code}": {
      "get": {
        "summary": "One story",
        "description": "Every outlet's headline for one story, with links.",
        "parameters": [{ "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The end of a story's storyPage link" }],
        "responses": { "200": { "description": "The story." }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/tip-check": {
      "post": {
        "summary": "Check a stock tip post",
        "description": "A rule-based check of the post's wording (hype, pressure, promised returns). It judges the post, never the stock. No AI.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["text"], "properties": { "text": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Red flags found, with the phrases." }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/ask": {
      "post": {
        "summary": "Ask Hypeless",
        "description": "An answer to a question about Indian market news, built from named outlets with a source for every sentence. Costs Rs 2 per call.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["question"], "properties": { "question": { "type": "string" } } } } } },
        "responses": { "200": { "description": "The cited answer." }, "default": { "$ref": "#/components/responses/Error" } }
      }
    }
  }
}