kokofinance-net Portfolio API
User portfolio management — analyze your cards, manage point balances, get redemption strategies.
User portfolio management — analyze your cards, manage point balances, get redemption strategies.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/kokofinance-net:kokofinance-net-portfolio-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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