kokofinance-net Intelligence API

openapi: 3.2.0
info:
  title: Koko Finance Intelligence API
  description: Credit card portfolio intelligence — analyze portfolios, compare cards, get recommendations, and check renewal value.
  version: 1.0.0
tags:
- name: Intelligence
  description: Computational endpoints — compare cards, get recommendations, calculate value, renewal analysis, merchant optimization.
paths:
  /api/v1/intelligence/compare:
    post:
      tags:
      - Intelligence
      summary: Compare Cards
      description: 'Compare credit cards side-by-side.


        fast mode: Deterministic comparison using UnifiedCardValueCalculator (<100ms).

        Returns side-by-side structured data for each card: fees, rewards,

        benefits, net value, break-even, and card metadata.


        verbose mode: Includes AI-generated winner recommendation, fit scores,

        pros/cons, and use-case recommendations (3-5s).'
      operationId: compare_cards_api_v1_intelligence_compare_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: mode
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ResponseMode'
          description: fast=deterministic <100ms, verbose=AI narrative 3-5s
          default: fast
        description: fast=deterministic <100ms, verbose=AI narrative 3-5s
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1CompareRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/intelligence/recommend:
    post:
      tags:
      - Intelligence
      summary: Recommend Cards
      description: 'Get card recommendations for a spending category.


        fast mode:

        Mode A (portfolio_card_names provided): Ranks portfolio cards by

        reward value for the requested category. No AI narrative.

        Mode B (no portfolio_card_names): Ranks market cards by net value.


        verbose mode:

        Mode A: Returns AI-generated headline, explanation, pro_tip,

        and alternative card narratives.

        Mode B: Same as fast (already deterministic, no AI needed).'
      operationId: recommend_cards_api_v1_intelligence_recommend_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: mode
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ResponseMode'
          description: fast=deterministic <100ms, verbose=AI narrative 2-4s
          default: fast
        description: fast=deterministic <100ms, verbose=AI narrative 2-4s
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1RecommendRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/intelligence/value:
    post:
      tags:
      - Intelligence
      summary: Calculate Card Value
      description: 'Calculate the financial value of a credit card.


        Always deterministic (no verbose mode). If card_name is provided, looks up

        the card in the database and uses actual rewards multipliers, benefits, and

        points program data. Otherwise, uses basic calculation with the provided

        annual_fee and spending values.'
      operationId: calculate_card_value_api_v1_intelligence_value_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1CardValueRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/intelligence/renewal:
    post:
      tags:
      - Intelligence
      summary: Renewal Check
      description: 'Check if a credit card is worth renewing.


        fast mode: Deterministic renewal verdict using calculate_renewal_verdict().

        Returns RENEW, DOWNGRADE, or CANCEL_AND_REPLACE verdict with downgrade

        and replacement options.


        verbose mode: Same deterministic verdict plus AI-generated detailed analysis,

        retention tips, and timing guidance (uses asyncio.to_thread for Gemini call).'
      operationId: renewal_check_api_v1_intelligence_renewal_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: mode
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ResponseMode'
          description: fast=deterministic <100ms, verbose=AI narrative 3-10s
          default: fast
        description: fast=deterministic <100ms, verbose=AI narrative 3-10s
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1RenewalCheckRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/intelligence/merchant/best-card:
    post:
      tags:
      - Intelligence
      summary: Merchant Best Card
      description: 'Find the best card from your portfolio for a purchase at a specific merchant.


        Resolves the merchant to a spending category, then ranks your cards by

        reward value. Deterministic for known merchants; uses Gemini fallback

        for unknown merchants.'
      operationId: merchant_best_card_api_v1_intelligence_merchant_best_card_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhichCardAtMerchantRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/intelligence/merchant/benefits:
    post:
      tags:
      - Intelligence
      summary: Merchant Benefits
      description: 'Check if any of your cards have credits or benefits at a specific merchant.


        Also includes an earning recommendation (which card earns most here).'
      operationId: merchant_benefits_api_v1_intelligence_merchant_benefits_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantBenefitsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    MerchantBenefitsRequest:
      properties:
        merchant:
          type: string
          title: Merchant
          description: Merchant name (e.g. 'Saks Fifth Avenue', 'Uber')
        portfolio:
          items:
            type: string
          type: array
          title: Portfolio
          description: List of card names in user's portfolio
      type: object
      required:
      - merchant
      - portfolio
      title: MerchantBenefitsRequest
      description: Request for POST /api/v1/intelligence/merchant/benefits
    V1CompareRequest:
      properties:
        card_names:
          items:
            type: string
          type: array
          maxItems: 3
          minItems: 2
          title: Card Names
          description: 2-3 card names to compare
        params:
          anyOf:
          - $ref: '#/components/schemas/ClientParameters'
          - type: 'null'
          description: Optional spending and preference parameters
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
          description: ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB'). Scopes card lookup to that market.
      type: object
      required:
      - card_names
      title: V1CompareRequest
      description: Request for POST /api/v1/intelligence/compare
      example:
        card_names:
        - Chase Sapphire Preferred
        - Capital One Venture X
        params:
          primary_goal: travel
          spending:
            dining: 400
            groceries: 300
            travel: 500
    SpendingInput:
      properties:
        groceries:
          anyOf:
          - type: number
          - type: 'null'
          title: Groceries
          description: Monthly grocery spend
          example: 600
        dining:
          anyOf:
          - type: number
          - type: 'null'
          title: Dining
          description: Monthly dining/restaurant spend
          example: 400
        travel:
          anyOf:
          - type: number
          - type: 'null'
          title: Travel
          description: Monthly travel spend
          example: 200
        gas:
          anyOf:
          - type: number
          - type: 'null'
          title: Gas
          description: Monthly gas/fuel spend
          example: 150
        streaming:
          anyOf:
          - type: number
          - type: 'null'
          title: Streaming
          description: Monthly streaming services spend
          example: 45
        shopping:
          anyOf:
          - type: number
          - type: 'null'
          title: Shopping
          description: Monthly general shopping spend
          example: 300
        other:
          anyOf:
          - type: number
          - type: 'null'
          title: Other
          description: Monthly other spend
          example: 200
        total_monthly:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Monthly
          description: Total monthly spend override
          example: 1895
      type: object
      title: SpendingInput
      description: Monthly spending by category (dollars)
    V1RecommendRequest:
      properties:
        category:
          type: string
          title: Category
          description: 'Spending category: dining, travel, groceries, gas, etc.'
        amount:
          anyOf:
          - type: number
          - type: 'null'
          title: Amount
          description: Monthly spend amount for this category
          default: 100
        portfolio_card_names:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Portfolio Card Names
          description: If provided, recommend from portfolio instead of market
        params:
          anyOf:
          - $ref: '#/components/schemas/ClientParameters'
          - type: 'null'
          description: Optional spending and preference parameters
      type: object
      required:
      - category
      title: V1RecommendRequest
      description: Request for POST /api/v1/cards/recommend
      example:
        category: dining
        params:
          credit_tier: excellent
          primary_goal: cashback
          spending:
            dining: 600
            groceries: 400
    V1RenewalCheckRequest:
      properties:
        card_name:
          type: string
          title: Card Name
          description: Name of the card to check for renewal
        card_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Card Id
          description: Matched card ID if known
        acquired_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Acquired Date
          description: Date card was acquired (YYYY-MM-DD)
        portfolio_card_names:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Portfolio Card Names
          description: Other cards in portfolio for context
        benefit_selections:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Benefit Selections
          description: Individual benefit keys the user uses (e.g. ['uber', 'dining', 'admirals_club']). Selected at 100%, unselected at 0%.
        benefit_categories_used:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Benefit Categories Used
          description: Benefit categories the user uses (e.g. ['dining_credit', 'lounge_access']). benefit_selections provides finer control.
        params:
          anyOf:
          - $ref: '#/components/schemas/ClientParameters'
          - type: 'null'
          description: Optional spending and preference parameters
      type: object
      required:
      - card_name
      title: V1RenewalCheckRequest
      description: Request for POST /api/v1/card/renewal-check
      example:
        card_name: Chase Sapphire Preferred
        params:
          primary_goal: travel
          spending:
            dining: 400
            groceries: 500
            travel: 300
    ClientParameters:
      properties:
        issuer_preferences:
          anyOf:
          - items:
              $ref: '#/components/schemas/IssuerPreference'
            type: array
          - type: 'null'
          title: Issuer Preferences
        credit_tier:
          anyOf:
          - type: string
            pattern: ^(poor|fair|good|excellent)$
          - type: 'null'
          title: Credit Tier
        spending:
          anyOf:
          - $ref: '#/components/schemas/SpendingInput'
          - type: 'null'
        point_balances:
          anyOf:
          - items:
              $ref: '#/components/schemas/InlinePointBalance'
            type: array
          - type: 'null'
          title: Point Balances
          description: Point/miles balances for enrichment. API consumers provide these per-request.
        primary_goal:
          anyOf:
          - type: string
            pattern: ^(travel|cashback|build_credit|business|balance_transfer)$
          - type: 'null'
          title: Primary Goal
        benefit_selections:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Benefit Selections
          description: 'Individual benefit keys the user actually uses. Selected benefits count at 100%, unselected at 0%. If omitted, all benefits use the default 50% utilization. Common keys: uber, dining, travel, airline_fee, hotel_fhr, saks, clear_plus, digital_entertainment, admirals_club, global_entry, lyft, grubhub. Use GET /api/v1/benefit-categories for the full registry.'
        benefit_categories_used:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Benefit Categories Used
          description: 'Standard benefit categories the user uses (alternative to benefit_selections). Each category maps to one or more individual benefit keys. Valid values: dining_credit, travel_credit, hotel_credit, lounge_access, shopping_credit, entertainment_credit, business_credit, loyalty_bonus, other. Note: benefit_selections provides finer control.'
        renewal_cancel_threshold:
          anyOf:
          - type: number
          - type: 'null'
          title: Renewal Cancel Threshold
          description: 'Net value below this → CANCEL_AND_REPLACE. Default: -100'
        renewal_keep_threshold:
          anyOf:
          - type: number
          - type: 'null'
          title: Renewal Keep Threshold
          description: 'Net value at or above this → RENEW. Default: 50'
      type: object
      title: ClientParameters
      description: 'Configurable parameters for B2B API consumption.


        These parameters allow API clients (issuers, fintechs) to customize

        KoKo''s analysis for their use case without changing core logic.'
      example:
        benefit_selections:
        - uber
        - dining
        - travel
        - admirals_club
        credit_tier: excellent
        primary_goal: travel
        spending:
          dining: 500
          gas: 100
          groceries: 400
          other: 150
          shopping: 200
          streaming: 30
          travel: 300
    IssuerPreference:
      properties:
        issuer:
          type: string
          title: Issuer
          description: Card issuer name
          example: Chase
        weight:
          type: number
          maximum: 3.0
          minimum: 0.1
          title: Weight
          description: 1.0 = neutral, >1.0 = boost, <1.0 = de-boost
          default: 1.0
          example: 1.5
      type: object
      required:
      - issuer
      title: IssuerPreference
      description: Boost or de-boost a specific issuer in recommendations
    V1CardValueRequest:
      properties:
        card_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Card Name
          description: Card name to look up. If provided, uses actual card benefits from DB.
        annual_spending:
          type: number
          title: Annual Spending
          description: Total annual spending on this card
          example: 30000
        annual_fee:
          type: number
          title: Annual Fee
          description: Annual fee for the card
          example: 95
        monthly_spending:
          anyOf:
          - additionalProperties:
              type: number
            type: object
          - type: 'null'
          title: Monthly Spending
          description: Per-category monthly spending
          example:
            dining: 500
            groceries: 400
            travel: 300
        sign_on_bonus:
          anyOf:
          - type: number
          - type: 'null'
          title: Sign On Bonus
          description: Sign-on bonus amount
          default: 0
        sign_on_bonus_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Sign On Bonus Type
          description: Sign-on bonus type (points or cashback)
          default: points
        params:
          anyOf:
          - $ref: '#/components/schemas/ClientParameters'
          - type: 'null'
          description: Optional parameters
      type: object
      required:
      - annual_spending
      - annual_fee
      title: V1CardValueRequest
      description: Request for POST /api/v1/intelligence/value
      example:
        annual_fee: 95
        annual_spending: 30000
        card_name: Chase Sapphire Preferred
        monthly_spending:
          dining: 500
          groceries: 400
          travel: 300
        sign_on_bonus: 60000
        sign_on_bonus_type: points
    InlinePointBalance:
      properties:
        program:
          type: string
          title: Program
          description: Program key
          example: chase_ur
        balance:
          type: integer
          title: Balance
          description: Point/miles balance
          example: 70000
      type: object
      required:
      - program
      - balance
      title: InlinePointBalance
      description: Point balance provided inline by API consumers (per-request, not stored)
    WhichCardAtMerchantRequest:
      properties:
        merchant:
          type: string
          title: Merchant
          description: Merchant name (e.g. 'Starbucks', 'Saks Fifth Avenue')
        amount:
          type: number
          title: Amount
          description: Purchase amount in dollars
          default: 100.0
        portfolio:
          items:
            type: string
          type: array
          title: Portfolio
          description: List of card names in user's portfolio
      type: object
      required:
      - merchant
      - portfolio
      title: WhichCardAtMerchantRequest
      description: Request for POST /api/v1/intelligence/merchant/best-card
    ResponseMode:
      type: string
      enum:
      - fast
      - verbose
      title: ResponseMode
      description: Response mode for intelligence endpoints.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: 'Your Koko API key (format: koko_xxxxx)'
      in: header
      name: X-API-Key