kokofinance-net International API

openapi: 3.2.0
info:
  title: Koko Finance International API
  description: Credit card portfolio intelligence — analyze portfolios, compare cards, get recommendations, and check renewal value.
  version: 1.0.0
tags:
- name: International
paths:
  /api/v1/{country}/cards/:
    get:
      tags:
      - International
      summary: Market List Cards
      description: 'List credit cards available in this market.


        Same data as GET /api/v1/cards/?country={country} but with the market

        in the URL path for clearer API organization.'
      operationId: market_list_cards_api_v1__country__cards__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: country
        in: path
        required: true
        schema:
          type: string
          description: ISO 3166-1 alpha-2 country code (e.g. 'gb', 'us')
          title: Country
        description: ISO 3166-1 alpha-2 country code (e.g. 'gb', 'us')
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Fuzzy search across card name, issuer, and best_for
          title: Q
        description: Fuzzy search across card name, issuer, and best_for
      - name: issuer
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by issuer (e.g. 'HSBC')
          title: Issuer
        description: Filter by issuer (e.g. 'HSBC')
      - name: card_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by card type (e.g. 'Travel Rewards')
          title: Card Type
        description: Filter by card type (e.g. 'Travel Rewards')
      - name: tag
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by tag (e.g. 'no_foreign_fee')
          title: Tag
        description: Filter by tag (e.g. 'no_foreign_fee')
      - name: max_annual_fee
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Maximum annual fee
          title: Max Annual Fee
        description: Maximum annual fee
      - name: network
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by network (Visa, Mastercard, Amex)
          title: Network
        description: Filter by network (Visa, Mastercard, Amex)
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Offset for pagination
          default: 0
          title: Offset
        description: Offset for pagination
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Results per page (max 100)
          default: 20
          title: Limit
        description: Results per page (max 100)
      - name: sort_by
        in: query
        required: false
        schema:
          type: string
          pattern: ^(card_name|annual_fee|issuer)$
          description: Sort field
          default: card_name
          title: Sort By
        description: Sort field
      - name: sort_order
        in: query
        required: false
        schema:
          type: string
          pattern: ^(asc|desc)$
          description: Sort direction
          default: asc
          title: Sort Order
        description: Sort direction
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Opaque cursor for pagination
          title: Cursor
        description: Opaque cursor for pagination
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/{country}/cards/{card_id}:
    get:
      tags:
      - International
      summary: Market Get Card Detail
      description: 'Get the full enriched card object for a card in this market.


        Card ID is globally unique. The market prefix organizes the API

        so international developers see only relevant endpoints.'
      operationId: market_get_card_detail_api_v1__country__cards__card_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: card_id
        in: path
        required: true
        schema:
          type: integer
          title: Card Id
      - name: country
        in: path
        required: true
        schema:
          type: string
          description: ISO 3166-1 alpha-2 country code
          title: Country
        description: ISO 3166-1 alpha-2 country code
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/{country}/cards/search:
    post:
      tags:
      - International
      summary: Market Search Cards
      description: 'Search for credit cards in this market.


        Same as POST /api/v1/cards/search but the market is specified in the

        URL path. The country field in the request body is overridden by the

        path value.'
      operationId: market_search_cards_api_v1__country__cards_search_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: country
        in: path
        required: true
        schema:
          type: string
          description: ISO 3166-1 alpha-2 country code
          title: Country
        description: ISO 3166-1 alpha-2 country code
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1CardSearchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/{country}/cards/compare:
    post:
      tags:
      - International
      summary: Market Compare Cards
      description: 'Compare credit cards side-by-side in this market.


        Cards are looked up within the specified market. Fast mode returns

        deterministic value calculations; verbose mode includes AI narrative.'
      operationId: market_compare_cards_api_v1__country__cards_compare_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: country
        in: path
        required: true
        schema:
          type: string
          description: ISO 3166-1 alpha-2 country code
          title: Country
        description: ISO 3166-1 alpha-2 country code
      - 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:
                $ref: '#/components/schemas/APIResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
    APIResponse:
      properties:
        success:
          type: boolean
          title: Success
        data:
          title: Data
        metadata:
          $ref: '#/components/schemas/APIMetadata'
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      type: object
      required:
      - success
      - data
      title: APIResponse
    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)
    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
    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)
    ResponseMode:
      type: string
      enum:
      - fast
      - verbose
      title: ResponseMode
      description: Response mode for intelligence endpoints.
    APIMetadata:
      properties:
        request_id:
          type: string
          title: Request Id
        api_version:
          type: string
          title: Api Version
          default: v1
        latency_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Latency Ms
        mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Mode
          description: 'Endpoint mode: ''fast'' (deterministic, <100ms) or ''verbose'' (includes AI narrative, 3-5s)'
        timestamp:
          type: string
          title: Timestamp
      type: object
      title: APIMetadata
    V1CardSearchRequest:
      properties:
        card_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Card Type
          description: 'Card type filter: travel, cashback, balance_transfer, business, student, hotel, airline'
        max_annual_fee:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Annual Fee
          description: Maximum annual fee in dollars (e.g. 200). Omit for no limit.
        issuer:
          anyOf:
          - type: string
          - type: 'null'
          title: Issuer
          description: Filter by issuer (e.g. 'Chase', 'American Express', 'Capital One')
        spending:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Spending
          description: 'Monthly spending by category for ranking (e.g. {"dining": 500, "travel": 300})'
        max_results:
          anyOf:
          - type: integer
            maximum: 20.0
            minimum: 1.0
          - type: 'null'
          title: Max Results
          description: Maximum number of results (1-20, default 5)
          default: 5
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
          description: ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB'). Defaults to 'US'.
      type: object
      title: V1CardSearchRequest
      description: Request for POST /search
      example:
        card_type: travel
        country: US
        max_annual_fee: 300
        max_results: 5
        spending:
          dining: 500
          groceries: 300
          travel: 400
    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