{
  "name": "Stockington API",
  "version": "2.0.0",
  "description": "Build and resolve \"boards\" of stocks, manage shortlists of positions, and fetch historical chart data for the Stockington multi-view. Boards are stateless (symbols in the URL). Shortlists are persisted in SQLite. Quotes are resolved server-side via Yahoo Finance public endpoints (no API key).",
  "conventions": {
    "symbols": "Comma/space separated. Accepts bare tickers (AAPL), $TICKER, or full Yahoo Finance URLs (finance.yahoo.com/quote/AAPL). Symbols are uppercased and de-duped.",
    "board": "A board is fully described by its symbols. To \"save\" a board, keep its url.",
    "shortlists": "A shortlist is a named, server-side collection of positions (shares + cost). Persisted in SQLite at ST_DB_PATH (default ./data/stockington.db). Each shortlist has a 12-char hex id. Positions are resolved with live quotes + P&L on read.",
    "cors": "All endpoints send Access-Control-Allow-Origin: *",
    "responses": "JSON. Errors look like { \"error\": \"...\" } with an appropriate status code.",
    "rest_aliases": "REST-style paths mirror the flat ones: /api/get/stock/{sym} = /api/quote/{sym}, /api/add/stock = /api/add, /api/get/stocklist = /api/list, etc."
  },
  "database": {
    "available": true,
    "path": "default"
  },
  "endpoints": [
    {
      "method": "GET",
      "path": "/api",
      "desc": "This documentation."
    },
    {
      "method": "GET",
      "path": "/api/health",
      "desc": "Liveness check."
    },
    {
      "method": "GET",
      "path": "/api/skill",
      "desc": "The Stockington agent skill (SKILL.md). Add ?format=json for metadata + install command.",
      "example": "https://stockington.vercel.app/api/skill"
    },
    {
      "method": "GET",
      "path": "/api/quote/{symbol}",
      "desc": "Resolve one stock (price, change, day range, 52w range, volume, intraday sparkline). REST alias: /api/get/stock/{symbol}.",
      "example": "https://stockington.vercel.app/api/quote/AAPL"
    },
    {
      "method": "GET|POST",
      "path": "/api/board?s=AAPL,MSFT",
      "desc": "Resolve a board. Returns the openable board url + each quote. POST body: {\"symbols\":[...]}. ?resolve=0 skips metadata. REST alias: /api/get/board.",
      "example": "https://stockington.vercel.app/api/board?s=AAPL,MSFT,NVDA"
    },
    {
      "method": "GET|POST",
      "path": "/api/add?s=NVDA&board=AAPL,MSFT",
      "desc": "Append symbols to an (optional) existing board → new board url. ?redirect=1 302s to the live board. REST alias: /api/add/stock.",
      "example": "https://stockington.vercel.app/api/add?s=NVDA&redirect=1"
    },
    {
      "method": "GET|POST",
      "path": "/api/remove?s=AAPL&board=AAPL,MSFT,GOOG",
      "desc": "Remove symbols from a board → new board url. REST alias: /api/remove/stock.",
      "example": "https://stockington.vercel.app/api/remove?board=AAPL,MSFT,GOOG&s=AAPL"
    },
    {
      "method": "GET",
      "path": "/api/search?q=apple",
      "desc": "Search for ticker symbols by name (up to 8 equity matches with exchange/sector).",
      "example": "https://stockington.vercel.app/api/search?q=apple"
    },
    {
      "method": "GET",
      "path": "/api/list",
      "desc": "Index of all predefined lists. REST alias: /api/get/stocklist.",
      "example": "https://stockington.vercel.app/api/list"
    },
    {
      "method": "GET",
      "path": "/api/list/{name}",
      "desc": "Get a predefined list of symbols. ?resolve=1 also resolves each quote. Lists: mag7, dow30, sp10, indexes, semis, banks, energy, crypto, ev, ai. REST alias: /api/get/stocklist/{name}.",
      "example": "https://stockington.vercel.app/api/list/mag7"
    },
    {
      "method": "GET",
      "path": "/api/chart/{symbol}?range=1mo&interval=1d",
      "desc": "Historical OHLC candles. range: 1d,5d,1mo,3mo,6mo,1y,2y,5y,10y,ytd,max. interval: 1m,5m,15m,30m,60m,1d,1wk,1mo.",
      "example": "https://stockington.vercel.app/api/chart/AAPL?range=3mo&interval=1d"
    },
    {
      "method": "GET",
      "path": "/api/market",
      "desc": "US market status (open/closed) + major index (SPY/QQQ/DIA/IWM) snapshot.",
      "example": "https://stockington.vercel.app/api/market"
    },
    {
      "method": "GET",
      "path": "/api/shortlists",
      "desc": "List all stored shortlists (id, name, positionCount). REST alias: /api/get/shortlists.",
      "example": "https://stockington.vercel.app/api/shortlists"
    },
    {
      "method": "POST",
      "path": "/api/shortlist",
      "desc": "Create a new shortlist. Body: {\"name\":\"My Picks\"}. Returns {id, name, positions:[]}. REST alias: /api/add/shortlist.",
      "example": "POST https://stockington.vercel.app/api/shortlist {\"name\":\"Tech picks\"}"
    },
    {
      "method": "GET|DELETE|PATCH",
      "path": "/api/shortlist/{id}",
      "desc": "GET: fetch shortlist with positions resolved (live quotes + P&L). ?resolve=0 skips. DELETE: remove shortlist. PATCH: rename (body: {\"name\":\"...\"}). REST aliases: /api/get/shortlist/{id}, /api/remove/shortlist/{id}.",
      "example": "https://stockington.vercel.app/api/shortlist/abc123"
    },
    {
      "method": "POST",
      "path": "/api/shortlist/{id}/position",
      "desc": "Add/update a position. Body: {\"symbol\":\"AAPL\",\"shares\":10,\"cost\":280}. Upserts on symbol. REST alias: /api/add/position (with shortlist_id in body).",
      "example": "POST https://stockington.vercel.app/api/shortlist/abc123/position {\"symbol\":\"AAPL\",\"shares\":10,\"cost\":280}"
    },
    {
      "method": "DELETE",
      "path": "/api/shortlist/{id}/position/{symbol}",
      "desc": "Remove a position from a shortlist. REST alias: /api/remove/position (with shortlist_id + symbol in query/body).",
      "example": "DELETE https://stockington.vercel.app/api/shortlist/abc123/position/AAPL"
    }
  ],
  "lists": [
    "mag7",
    "dow30",
    "sp10",
    "indexes",
    "semis",
    "banks",
    "energy",
    "crypto",
    "ev",
    "ai"
  ],
  "quickstart": {
    "1_build_a_board": "GET https://stockington.vercel.app/api/add?s=AAPL,MSFT,NVDA",
    "2_open_it": "the \"url\" field, e.g. https://stockington.vercel.app/?s=AAPL,MSFT,NVDA",
    "3_inspect_a_quote": "GET https://stockington.vercel.app/api/quote/AAPL",
    "4_load_a_preset": "GET https://stockington.vercel.app/api/list/mag7",
    "5_create_shortlist": "POST https://stockington.vercel.app/api/shortlist {\"name\":\"My picks\"}",
    "6_add_position": "POST https://stockington.vercel.app/api/shortlist/<id>/position {\"symbol\":\"AAPL\",\"shares\":10,\"cost\":280}",
    "7_check_pnl": "GET https://stockington.vercel.app/api/shortlist/<id>",
    "8_chart_data": "GET https://stockington.vercel.app/api/chart/AAPL?range=6mo&interval=1d",
    "9_market_status": "GET https://stockington.vercel.app/api/market"
  },
  "skill": {
    "description": "An installable agent skill (SKILL.md) for using this API lives at /api/skill.",
    "url": "https://stockington.vercel.app/api/skill",
    "install": "mkdir -p .devin/skills/stockington && curl -s https://stockington.vercel.app/api/skill -o .devin/skills/stockington/SKILL.md"
  },
  "app": "https://stockington.vercel.app/"
}