{
 "openapi": "3.1.0",
 "info": {
  "title": "Faro Data API",
  "version": "1.0.0",
  "description": "Daily-updated U.S. market data: federal contract awards sized against the winner's market cap (contract shocks), Faro DNA scores for 340+ stocks, strong stocks on sale, and an IPO radar. Educational data compiled from public sources. Not investment advice."
 },
 "servers": [
  {
   "url": "https://faro-economicopages.com"
  }
 ],
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer"
   },
   "apiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
   }
  }
 },
 "security": [
  {},
  {
   "bearer": []
  },
  {
   "apiKey": []
  }
 ],
 "paths": {
  "/api/v1/contracts": {
   "get": {
    "operationId": "federal_contracts",
    "summary": "Federal contract awards to public companies",
    "description": "Recent U.S. federal contract awards (Department of War daily announcements + USAspending) won by publicly traded companies, newest first. Each award includes its size as a % of the winner's market cap and the stock move since the announcement.",
    "parameters": [
     {
      "name": "days",
      "in": "query",
      "required": false,
      "description": "Look-back window in days (1–60). Default 30.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "agency",
      "in": "query",
      "required": false,
      "description": "Filter by agency name (contains), e.g. Navy, Army, Air Force.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "min_amount",
      "in": "query",
      "required": false,
      "description": "Minimum award amount in USD.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Max rows (1–200). Default 25.",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK (JSON)"
     },
     "401": {
      "description": "Invalid API key"
     },
     "402": {
      "description": "Payment required: free tier used up or no credits. Body includes checkout URLs."
     }
    }
   }
  },
  "/api/v1/contracts/shocks": {
   "get": {
    "operationId": "contract_shocks",
    "summary": "Contract shocks (award ≥ X% of market cap)",
    "description": "Federal awards that are large relative to the winning company's size: award value ÷ market cap ≥ min_pct. A $500M award means little to a $200B prime but a lot to a $5B company.",
    "parameters": [
     {
      "name": "min_pct",
      "in": "query",
      "required": false,
      "description": "Minimum award as % of market cap. Default 1 (= 1%).",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "days",
      "in": "query",
      "required": false,
      "description": "Look-back window in days (1–60). Default 60.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "exclude_ceilings",
      "in": "query",
      "required": false,
      "description": "Exclude IDIQ ceiling values. Default false.",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Max rows (1–100). Default 20.",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK (JSON)"
     },
     "401": {
      "description": "Invalid API key"
     },
     "402": {
      "description": "Payment required: free tier used up or no credits. Body includes checkout URLs."
     }
    }
   }
  },
  "/api/v1/contracts/recipients": {
   "get": {
    "operationId": "contract_recipients",
    "summary": "Top public contract recipients",
    "description": "Public companies ranked by total federal awards in the window relative to their market cap, with award count, largest award and stock move since the first award.",
    "parameters": [
     {
      "name": "sort",
      "in": "query",
      "required": false,
      "description": "Ranking. Default pct_of_market_cap.",
      "schema": {
       "type": "string",
       "enum": [
        "pct_of_market_cap",
        "total"
       ]
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Max rows (1–100). Default 20.",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK (JSON)"
     },
     "401": {
      "description": "Invalid API key"
     },
     "402": {
      "description": "Payment required: free tier used up or no credits. Body includes checkout URLs."
     }
    }
   }
  },
  "/api/v1/dna/{ticker}": {
   "get": {
    "operationId": "stock_dna",
    "summary": "Faro DNA score of one stock",
    "description": "The Faro DNA score (0–100) of a U.S. stock and its 7 pillars: track record, revenue, quality, cash, price, balance sheet and federal-money flow. Levels: fuerte (strong), prometedor (promising), mixto (mixed), debil (weak).",
    "parameters": [
     {
      "name": "ticker",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK (JSON)"
     },
     "401": {
      "description": "Invalid API key"
     },
     "402": {
      "description": "Payment required: free tier used up or no credits. Body includes checkout URLs."
     }
    }
   }
  },
  "/api/v1/dna": {
   "get": {
    "operationId": "rank_dna",
    "summary": "Rank stocks by Faro DNA",
    "description": "Ranking of 340+ U.S. stocks by Faro DNA score, filterable by minimum score, level and sector.",
    "parameters": [
     {
      "name": "min_score",
      "in": "query",
      "required": false,
      "description": "Minimum DNA score (0–100).",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "level",
      "in": "query",
      "required": false,
      "description": "DNA level.",
      "schema": {
       "type": "string",
       "enum": [
        "fuerte",
        "prometedor",
        "mixto",
        "debil"
       ]
      }
     },
     {
      "name": "sector",
      "in": "query",
      "required": false,
      "description": "Sector (contains), e.g. Technology, Industrials, Healthcare.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Max rows (1–200). Default 25.",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK (JSON)"
     },
     "401": {
      "description": "Invalid API key"
     },
     "402": {
      "description": "Payment required: free tier used up or no credits. Body includes checkout URLs."
     }
    }
   }
  },
  "/api/v1/dips": {
   "get": {
    "operationId": "quality_dips",
    "summary": "Strong stocks on sale",
    "description": "Stocks with 15+ years of strong history (≥7%/yr, ≥60% positive years) now 3–25% below their all-time high. Includes 1/3/5/7/10-year total returns, 10- and 20-year CAGR, volatility, dividend yield and DNA score.",
    "parameters": [
     {
      "name": "sector",
      "in": "query",
      "required": false,
      "description": "Faro sector key (tech, defense=defensa, space=espacio, biotech=bio, energy=energia, logistics=logistica, classics=clasicas, dividends=dividendos, finance=finanzas, real estate=realestate, mining=mineria).",
      "schema": {
       "type": "string",
       "enum": [
        "tech",
        "defensa",
        "espacio",
        "bio",
        "energia",
        "logistica",
        "clasicas",
        "dividendos",
        "finanzas",
        "realestate",
        "mineria"
       ]
      }
     },
     {
      "name": "max_drawdown_pct",
      "in": "query",
      "required": false,
      "description": "Only stocks at most this far below their high, e.g. 15.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "description": "Language of descriptions. Default en.",
      "schema": {
       "type": "string",
       "enum": [
        "en",
        "es"
       ]
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Max rows (1–100). Default 20.",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK (JSON)"
     },
     "401": {
      "description": "Invalid API key"
     },
     "402": {
      "description": "Payment required: free tier used up or no credits. Body includes checkout URLs."
     }
    }
   }
  },
  "/api/v1/ipos": {
   "get": {
    "operationId": "ipo_radar",
    "summary": "IPO radar",
    "description": "U.S. IPOs of the last 13 months with return since IPO, DNA score, revenue growth and lock-up date; plus upcoming IPOs.",
    "parameters": [
     {
      "name": "below_ipo",
      "in": "query",
      "required": false,
      "description": "Only IPOs trading below their IPO price.",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "sort",
      "in": "query",
      "required": false,
      "description": "Default date (newest first).",
      "schema": {
       "type": "string",
       "enum": [
        "date",
        "return",
        "dna"
       ]
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Max rows (1–150). Default 20.",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK (JSON)"
     },
     "401": {
      "description": "Invalid API key"
     },
     "402": {
      "description": "Payment required: free tier used up or no credits. Body includes checkout URLs."
     }
    }
   }
  },
  "/api/v1/stock/{ticker}": {
   "get": {
    "operationId": "stock_profile",
    "summary": "Everything the Faro knows about one stock",
    "description": "One call: DNA score and pillars, federal contracts of the last 60 days, contract-size stats, price vs 52-week high, long-term returns and IPO data when applicable.",
    "parameters": [
     {
      "name": "ticker",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "description": "Language of descriptions.",
      "schema": {
       "type": "string",
       "enum": [
        "en",
        "es"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK (JSON)"
     },
     "401": {
      "description": "Invalid API key"
     },
     "402": {
      "description": "Payment required: free tier used up or no credits. Body includes checkout URLs."
     }
    }
   }
  },
  "/api/v1/account": {
   "get": {
    "operationId": "account",
    "summary": "Your credits and free tier",
    "description": "Credits left on your API key (or free calls left today without a key) and how to buy more. Free; does not use a credit.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK (JSON)"
     },
     "401": {
      "description": "Invalid API key"
     },
     "402": {
      "description": "Payment required: free tier used up or no credits. Body includes checkout URLs."
     }
    }
   }
  }
 }
}