kokofinance-net Portfolio API

openapi: 3.2.0
info:
  title: Koko Finance Portfolio API
  description: Credit card portfolio intelligence — analyze portfolios, compare cards, get recommendations, and check renewal value.
  version: 1.0.0
tags:
- name: Portfolio
  description: User portfolio management — analyze your cards, manage point balances, get redemption strategies.
paths:
  /api/v1/portfolio/analyze:
    post:
      tags:
      - Portfolio
      summary: Analyze credit card portfolio
      description: Portfolio analysis with card-by-card value breakdowns and decisions. Use ?mode=fast for deterministic-only (<100ms) or ?mode=verbose for AI narrative (3-5s).
      operationId: v1_analyze_portfolio_api_v1_portfolio_analyze_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/V1PortfolioAnalyzeRequest'
      responses:
        '200':
          description: Portfolio analysis with card-by-card breakdown
          content:
            application/json:
              schema: {}
        '401':
          description: Invalid or missing API key
        '429':
          description: Rate limit exceeded (60 requests/minute)
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/portfolio/points-playbook:
    post:
      tags:
      - Portfolio
      summary: Generate points redemption playbook
      description: Generates concrete redemption strategies for credit card point balances. Returns per-program suggestions, cashback earning estimate, and points-at-risk warnings.
      operationId: v1_points_playbook_api_v1_portfolio_points_playbook_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/V1PlaybookRequest'
      responses:
        '200':
          description: Points playbook with per-program redemption suggestions
          content:
            application/json:
              schema: {}
        '401':
          description: Invalid or missing API key
        '429':
          description: Rate limit exceeded (60 requests/minute)
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/portfolio/points/balances:
    get:
      tags:
      - Portfolio
      summary: Get Balances
      description: Get current user's stored balances enriched with program data.
      operationId: get_balances_api_v1_portfolio_points_balances_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Guest-ID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Guest-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Portfolio
      summary: Save Balances
      description: Batch upsert point balances.
      operationId: save_balances_api_v1_portfolio_points_balances_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Guest-ID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Guest-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveBalancesRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/portfolio/points/balances/{program_key}:
    delete:
      tags:
      - Portfolio
      summary: Delete Balance
      description: Remove a balance entry for a specific program.
      operationId: delete_balance_api_v1_portfolio_points_balances__program_key__delete
      parameters:
      - name: program_key
        in: path
        required: true
        schema:
          type: string
          title: Program Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Guest-ID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Guest-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/portfolio/points/summary:
    get:
      tags:
      - Portfolio
      summary: Get Summary
      description: Get total estimated value across all programs with card-aware valuation.
      operationId: get_summary_api_v1_portfolio_points_summary_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Guest-ID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Guest-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SaveBalanceItem:
      properties:
        program_key:
          type: string
          title: Program Key
          description: Program key
          example: chase_ur
        balance:
          type: integer
          minimum: 0.0
          title: Balance
          description: Point/miles balance
          example: 70000
        expiration_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Expiration Date
          description: Expiration date (YYYY-MM-DD) if applicable
        program_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Program Name
          description: Program name (for free-text entries not in our system)
      type: object
      required:
      - program_key
      - balance
      title: SaveBalanceItem
      description: Single balance entry for batch save
    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)
    V1PortfolioAnalyzeRequest:
      properties:
        cards:
          items:
            $ref: '#/components/schemas/CardInput'
          type: array
          maxItems: 10
          minItems: 1
          title: Cards
          description: 1-10 credit cards to analyze
        analysis_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Analysis Type
          description: 'Analysis type: general, fees, benefits, or usage'
          default: general
        params:
          anyOf:
          - $ref: '#/components/schemas/ClientParameters'
          - type: 'null'
          description: Optional spending and preference parameters
      type: object
      required:
      - cards
      title: V1PortfolioAnalyzeRequest
      description: Request for POST /api/v1/portfolio/analyze
      example:
        cards:
        - annual_fee: 95
          card_name: Chase Sapphire Preferred
        - annual_fee: 250
          card_name: American Express Gold Card
        params:
          primary_goal: travel
          spending:
            dining: 500
            gas: 100
            groceries: 400
            other: 150
            shopping: 200
            streaming: 30
            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
    V1PlaybookRequest:
      properties:
        cards:
          items:
            type: string
          type: array
          maxItems: 10
          minItems: 1
          title: Cards
          description: 1-10 card names to analyze
        point_balances:
          anyOf:
          - items:
              $ref: '#/components/schemas/PlaybookBalanceInput'
            type: array
          - type: 'null'
          title: Point Balances
          description: Point/miles balances for generating redemption strategies
        spending:
          anyOf:
          - $ref: '#/components/schemas/SpendingInput'
          - type: 'null'
          description: Monthly spending for cashback calculation
      type: object
      required:
      - cards
      title: V1PlaybookRequest
      description: Request for POST /api/v1/portfolio/points-playbook
      example:
        cards:
        - Chase Sapphire Reserve
        - American Express Gold Card
        point_balances:
        - balance: 70000
          program_key: chase_ur
        - balance: 50000
          program_key: amex_mr
        spending:
          dining: 500
          groceries: 400
          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
    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)
    PlaybookBalanceInput:
      properties:
        program_key:
          type: string
          title: Program Key
          description: Program key
          example: chase_ur
        balance:
          type: integer
          minimum: 0.0
          title: Balance
          description: Point/miles balance
          example: 70000
      type: object
      required:
      - program_key
      - balance
      title: PlaybookBalanceInput
      description: Point balance for playbook request
    CardInput:
      properties:
        card_name:
          type: string
          title: Card Name
          description: Full card name
          example: Chase Sapphire Preferred
        annual_fee:
          anyOf:
          - type: integer
          - type: 'null'
          title: Annual Fee
          description: Annual fee override
          example: 95
        card_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Card Id
          description: Matched card ID if known
        sign_on_bonus:
          anyOf:
          - type: integer
          - type: 'null'
          title: Sign On Bonus
          description: Sign-on bonus amount
        sign_on_bonus_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Sign On Bonus Type
          description: Sign-on bonus type (points or cashback)
          default: points
      type: object
      required:
      - card_name
      title: CardInput
      description: Card in a portfolio
    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
    SaveBalancesRequest:
      properties:
        balances:
          items:
            $ref: '#/components/schemas/SaveBalanceItem'
          type: array
          maxItems: 50
          minItems: 1
          title: Balances
          description: Balances to save
      type: object
      required:
      - balances
      title: SaveBalancesRequest
      description: Request for POST /api/v1/points/balances — batch upsert
      example:
        balances:
        - balance: 70000
          program_key: chase_ur
        - balance: 50000
          program_key: amex_mr
    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