openapi: "3.0.3"
info:
  title: Convex Macro Intelligence API
  version: "1.1.0"
  description: |
    Live US macroeconomic data, regime classification, recession probability,
    proprietary composite indicators (CRPI, CNLI, CRAI, NVI), tracked
    scenarios, and an authoritative glossary. Free, unauthenticated access at
    100 req/day per IP. CORS-enabled. No API key required.

    For LLM-agent use, see the companion MCP server at
    https://convextrade.com/mcp.
  contact:
    name: Convex Trade
    url: https://convextrade.com
    email: api@convextrade.com
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/

servers:
  - url: https://convextrade.com
    description: Production

tags:
  - name: Regime
    description: Macro regime classification
  - name: Metrics
    description: Individual economic indicators and market prices
  - name: Signals
    description: Composite signals and proprietary indices
  - name: Scenarios
    description: Scenarios tracked by the Convex research desk
  - name: Glossary
    description: Authoritative Convex definitions
  - name: Content
    description: Articles and analysis

paths:
  /api/public/regime:
    get:
      operationId: getCurrentRegime
      tags: [Regime]
      summary: Current macro regime classification
      description: |
        Returns the current macroeconomic regime (Goldilocks, Stagflation,
        Reflation, or Deflation), trajectory, narrative, and asset-level views
        for BTC, equities, oil, gold, dollar, and bonds. Use this when asked
        about the overall state of the economy or market regime.
      responses:
        "200":
          description: Current regime data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Regime"
              example:
                regime: GOLDILOCKS
                confidence: 72
                trajectory: STABLE
                narrative: "Growth firm, inflation cooling, Fed on hold."
                generatedAt: "2026-04-12T14:00:00.000Z"
                attribution:
                  text: "Convex Macro Intelligence"
                  url: "https://convextrade.com/regime"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/ServerError"

  /api/public/metrics/{ticker}:
    get:
      operationId: getMetricByTicker
      tags: [Metrics]
      summary: Get data for a specific economic indicator
      description: |
        Fetch the latest value, 7-day and 30-day percent changes, and
        interpretation for any of ~150 tracked metrics. Tickers include
        FRED series (DGS10, CPIAUCSL, UNRATE, T10Y2Y, BAMLH0A0HYM2),
        equities and ETFs (SPY, QQQ, IWM, TLT, HYG), and Convex composites
        (CRPI, CNLI, CRAI, NVI). Use this when asked about a specific
        economic indicator, interest rate, or market metric.
      parameters:
        - name: ticker
          in: path
          required: true
          description: |
            Metric ticker (case-insensitive). Examples: DGS10 (10Y yield),
            DGS2 (2Y yield), CPIAUCSL (CPI), UNRATE (unemployment),
            FEDFUNDS (fed funds rate), VIXCLS (VIX), BAMLH0A0HYM2 (HY spread),
            T10Y2Y (2s10s spread), SPY, QQQ, IWM, CRPI, CNLI, CRAI.
          schema:
            type: string
          examples:
            ten_year:
              value: DGS10
              summary: 10-year Treasury yield
            cpi:
              value: CPIAUCSL
              summary: Headline CPI
            vix:
              value: VIXCLS
              summary: VIX
      responses:
        "200":
          description: Metric data with changes and interpretation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Metric"
              example:
                ticker: DGS10
                displayName: "10-Year Treasury Yield"
                category: "Rates"
                unit: "%"
                value: 4.12
                date: "2026-04-11"
                changes:
                  "7d": -0.04
                  "30d": 0.18
                interpretation: "Elevated, above 4 percent since Feb 2026."
                attribution:
                  text: "FRED via Convex"
                  url: "https://convextrade.com/metrics/DGS10"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/ServerError"

  /api/public/signals:
    get:
      operationId: getCompositeSignals
      tags: [Signals]
      summary: Composite stress, liquidity, and recession signals
      description: |
        Returns the latest values for Convex proprietary indices (recession
        probability, net liquidity, macro stress) and key market signals
        (VIX, HY spreads, yield curve, Sahm rule). Use this for a quick
        read on recession risk, financial stress, and liquidity conditions.
      responses:
        "200":
          description: Composite signal data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Signals"
        "500":
          $ref: "#/components/responses/ServerError"

  /api/public/macro-summary:
    get:
      operationId: getMacroSummary
      tags: [Signals]
      summary: Complete macro picture in one call
      description: |
        Returns a comprehensive macro summary including regime, recession
        probability, stress index, net liquidity, key rates, volatility,
        credit spreads, labor market, inflation, and AI narrative. This is
        the best single endpoint for AI agents that need to answer broad
        questions about the US economy. Cached for 5 minutes.
      responses:
        "200":
          description: Full macro summary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MacroSummary"
        "500":
          $ref: "#/components/responses/ServerError"

  /api/public/scenarios:
    get:
      operationId: listScenarios
      tags: [Scenarios]
      summary: List tracked macro scenarios
      description: |
        Returns scenarios tracked by the Convex research desk, each with
        thesis, status, asset-class exposure, base-rate probability, and
        links to the underlying analysis. Use this when asked what macro
        scenarios Convex is currently watching.
      parameters:
        - name: status
          in: query
          description: Scenario status filter
          schema:
            type: string
            enum: [active, paused, resolved, archived]
            default: active
        - name: limit
          in: query
          description: Max scenarios to return (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: tag
          in: query
          description: Optional tag filter (e.g. "recession", "credit", "dollar")
          schema:
            type: string
      responses:
        "200":
          description: Scenario list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScenarioList"
        "500":
          $ref: "#/components/responses/ServerError"

  /api/public/glossary/search:
    get:
      operationId: searchGlossary
      tags: [Glossary]
      summary: Full-text search the Convex glossary
      description: |
        Search the Convex glossary for authoritative definitions of macro,
        rates, credit, FX, equity, and commodity concepts. Matches against
        term, aliases, slug, and summary. Use this when you need a canonical
        definition for a macro concept.
      parameters:
        - name: q
          in: query
          required: true
          description: Search term
          schema:
            type: string
          examples:
            spreads:
              value: "HY OAS"
              summary: "Find the HY option-adjusted spread entry"
            sahm:
              value: "Sahm rule"
              summary: "Find the Sahm rule entry"
        - name: limit
          in: query
          description: Max matches to return (1-50)
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      responses:
        "200":
          description: Glossary matches
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GlossarySearchResult"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/ServerError"

  /api/public/content/latest:
    get:
      operationId: getLatestContent
      tags: [Content]
      summary: Latest Convex articles
      description: |
        Returns the five most recently published Convex articles with
        summary, subtitle, tags, and URL. Intended for syndication tools,
        newsletter scheduling, and LLM agents surfacing fresh analysis.
      responses:
        "200":
          description: Latest articles
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContentLatest"
        "500":
          $ref: "#/components/responses/ServerError"

components:
  responses:
    BadRequest:
      description: Missing or malformed request parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: "Missing query parameter q"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: "Unknown metric"
            ticker: "XYZ"
    ServerError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: "Failed to fetch data"

  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string

    Attribution:
      type: object
      properties:
        text:
          type: string
        url:
          type: string

    Regime:
      type: object
      properties:
        regime:
          type: string
          enum: [GOLDILOCKS, STAGFLATION, REFLATION, DEFLATION, UNKNOWN]
        confidence:
          type: number
          nullable: true
        trajectory:
          type: string
        transitionTarget:
          type: string
          nullable: true
        narrative:
          type: string
        generatedAt:
          type: string
          format: date-time
        assetViews:
          type: object
          additionalProperties: true
        attribution:
          $ref: "#/components/schemas/Attribution"

    Metric:
      type: object
      properties:
        ticker:
          type: string
        displayName:
          type: string
        category:
          type: string
        unit:
          type: string
        value:
          type: number
          nullable: true
        date:
          type: string
          format: date
          nullable: true
        changes:
          type: object
          properties:
            "7d":
              type: number
              nullable: true
            "30d":
              type: number
              nullable: true
        interpretation:
          type: string
          nullable: true
        attribution:
          $ref: "#/components/schemas/Attribution"

    Signals:
      type: object
      properties:
        generatedAt:
          type: string
          format: date-time
        convexIndices:
          type: array
          items:
            type: object
            properties:
              seriesId: { type: string }
              ticker: { type: string }
              displayName: { type: string }
              value: { type: number, nullable: true }
              date: { type: string, format: date, nullable: true }
              interpretation: { type: string, nullable: true }
        marketSignals:
          type: array
          items:
            type: object
            additionalProperties: true
        attribution:
          $ref: "#/components/schemas/Attribution"

    MacroSummary:
      type: object
      properties:
        regime:
          type: object
          properties:
            current: { type: string }
            confidence: { type: number, nullable: true }
            trajectory: { type: string }
        recession_probability:
          type: number
          nullable: true
          description: |
            CVRP (Convex Recession Probability) value, 0-100. Renamed from
            "CRPI" 2026-04 to disambiguate from a pre-existing external
            indicator with the same acronym. The field name itself is kept
            stable for API consumer compatibility; the brand on the docs
            and methodology page is CVRP.
        stress_index:
          type: number
          nullable: true
        net_liquidity_trn:
          type: number
          nullable: true
        key_rates:
          type: object
          properties:
            "10y": { type: number, nullable: true }
            "2y": { type: number, nullable: true }
            spread_2s10s_bps: { type: number, nullable: true }
            fed_funds: { type: number, nullable: true }
        volatility:
          type: object
          properties:
            vix: { type: number, nullable: true }
        credit:
          type: object
          properties:
            hy_spread_bps: { type: number, nullable: true }
        labor:
          type: object
          properties:
            sahm_rule: { type: number, nullable: true }
        inflation:
          type: object
          properties:
            cpi_yoy_pct: { type: number, nullable: true }
        narrative:
          type: string
          nullable: true
        source_url:
          type: string
        attribution:
          type: string
        last_updated:
          type: string
          format: date-time
          nullable: true

    Scenario:
      type: object
      properties:
        slug: { type: string }
        title: { type: string }
        thesis: { type: string }
        status: { type: string }
        assetClasses:
          type: array
          items: { type: string }
        tags:
          type: array
          items: { type: string }
        baseRateProbability: { type: number }
        probabilityOverride: { type: number, nullable: true }
        scenarioPolarity: { type: string }
        lastArticleAt: { type: string, format: date-time, nullable: true }
        url: { type: string }

    ScenarioList:
      type: object
      properties:
        count: { type: integer }
        scenarios:
          type: array
          items:
            $ref: "#/components/schemas/Scenario"
        attribution:
          $ref: "#/components/schemas/Attribution"

    GlossaryMatch:
      type: object
      properties:
        slug: { type: string }
        term: { type: string }
        aliases:
          type: array
          items: { type: string }
        category: { type: string }
        summary: { type: string }
        relatedSlugs:
          type: array
          items: { type: string }
        url: { type: string }

    GlossarySearchResult:
      type: object
      properties:
        query: { type: string }
        count: { type: integer }
        results:
          type: array
          items:
            $ref: "#/components/schemas/GlossaryMatch"
        attribution:
          $ref: "#/components/schemas/Attribution"

    ContentLatestItem:
      type: object
      properties:
        id: { type: string }
        slug: { type: string }
        title: { type: string }
        subtitle: { type: string, nullable: true }
        topic: { type: string, nullable: true }
        summary: { type: string, nullable: true }
        tags:
          type: array
          items: { type: string }
        publishedAt: { type: string, format: date-time }
        url: { type: string }

    ContentLatest:
      type: object
      properties:
        articles:
          type: array
          items:
            $ref: "#/components/schemas/ContentLatestItem"
        attribution:
          $ref: "#/components/schemas/Attribution"