REST API Reference

Authentication

All endpoints (except /platform/health) require an API key passed via the X-API-Key header:

X-API-Key: koko_your_api_key

Base URL

https://kokofinance.net/api/v1

Try it interactively in Swagger UI →

API Collections

Endpoints are organized into 5 collections based on what the consumer is trying to do:

Collection	Prefix	Purpose
Cards	`/api/v1/cards`	Card catalog, details, terms, history, search
Intelligence	`/api/v1/intelligence`	Computation & decision endpoints (compare, recommend, value, renewal, merchant)
Portfolio	`/api/v1/portfolio`	User portfolio management (analyze, playbook, points balances)
Reference	`/api/v1/reference`	Static lookups (points programs, benefit categories)
Platform	`/api/v1/platform`	System health, usage, billing, developer accounts

Fast vs Verbose Mode

Four endpoints support a ?mode=fast|verbose query parameter:

Endpoint	Fast (default)	Verbose
`/portfolio/analyze`	Deterministic calculations, <100ms	`?mode=verbose` — adds AI narrative (3-5s)
`/intelligence/compare`	Side-by-side data, <100ms	`?mode=verbose` — adds AI winner & pros/cons (3-5s)
`/intelligence/recommend`	Deterministic ranking, <100ms	`?mode=verbose` — adds AI headline & explanation (2-4s)
`/intelligence/renewal`	Deterministic verdict, <100ms	`?mode=verbose` — adds retention tips & timing guidance (3-5s)

The metadata.mode field in every response tells you which variant was used: "fast" or "verbose".

Response Envelope

All endpoints return a consistent envelope:

{
  "success": true,
  "data": { ... },
  "metadata": {
    "request_id": "a1b2c3d4e5f6",
    "api_version": "v1",
    "latency_ms": 52,
    "mode": "fast",
    "timestamp": "2026-05-24T14:30:00Z"
  },
  "error": null
}

Tier-Based Data Access

API responses are scoped by your plan tier. Evaluation-tier responses include a subset of fields suitable for testing; paid tiers receive the full enriched dataset. Affected endpoints return a _tier_restricted: true flag when data has been reduced.

Endpoint Limits by Tier

Control	Evaluation	Pro	Scale / Enterprise
Catalog page size (max)	20	100	100
Search results (max)	5	20	20
Unique card detail lookups / month	10	Unlimited	Unlimited
Bulk changelog (`GET /cards/changes`)	Blocked (403)	Allowed	Allowed

Unique card lookups count distinct card_id values accessed via GET /cards/{id}. Repeat access to the same card does not count against the limit.

Field Visibility — Catalog (`GET /cards`)

Field	Evaluation	Paid
`card_id`, `card_name`, `issuer`, `annual_fee`, `card_type`, `network`	✓	✓
`tags`, `credit_score_needed`, `best_for`, `is_active`	✗	✓

Field Visibility — Enriched Detail (`GET /cards/{id}`)

Section	Evaluation	Paid
`card_id`, `card_name`, `issuer`, `annual_fee`	✓	✓
`rewards.structure_text` (narrative)	✓	✓
`sign_on_bonus.description` (text)	✓	✓
`rewards.multipliers` (structured JSON)	✗	✓
`benefits.annual_credits` (array)	✗	✓
`benefits.one_time_benefits` (array)	✗	✓
`terms` (full Schumer Box)	✓	✓
`urls` (apply, affiliate)	✗	✓
`data_quality`	✗	✓

Field Visibility — Terms (`GET /cards/{id}/terms`)

Field	Evaluation	Paid
`card_id`, `card_name`, `issuer`, `purchase_apr`, `foreign_transaction_fee`	✓	✓
`cash_advance_apr`, `penalty_apr`, `balance_transfer_apr`, `late_fee`, `returned_payment_fee`, `promotional_apr`, `grace_period_days`	✗	✓

Field Visibility — Search (`POST /cards/search`)

Field	Evaluation	Paid
`card_name`, `issuer`, `annual_fee`, `card_type`, `match_score`, `reasoning`	✓	✓
`card_id`, `rewards_structure`, `key_benefits`, `sign_on_bonus`, `apply_url`	✗	✓

Tier-Restricted Response Signals

When a response has been field-stripped, two extra fields are appended:

{
  "card_id": 42,
  "card_name": "Chase Sapphire Reserve",
  "issuer": "Chase",
  "annual_fee": 550,
  "rewards": { "structure_text": "3x on travel and dining..." },
  "sign_on_bonus": { "description": "60,000 bonus points..." },
  "terms": {
    "purchase_apr": "22.49% - 29.49% Variable",
    "cash_advance_apr": "29.49% Variable",
    "penalty_apr": "Up to 29.99%",
    "balance_transfer_apr": "29.49% Variable",
    "late_fee": "Up to $40",
    "cash_advance_fee": "5%, min $10",
    "grace_period_days": 21
  },
  "_tier_restricted": true,
  "_upgrade_url": "https://kokofinance.net/pricing"
}

Tier-Gated Error Responses

Unique card limit exceeded (403):

{
  "detail": {
    "error": "unique_card_limit_exceeded",
    "message": "Evaluation tier allows 10 unique card detail lookups per month (10/10 used).",
    "upgrade_url": "https://kokofinance.net/pricing"
  }
}

Endpoint blocked for tier (403):

{
  "detail": {
    "error": "tier_restricted",
    "message": "Bulk changelog requires a paid plan (Pro or above).",
    "upgrade_url": "https://kokofinance.net/pricing"
  }
}

Cards Collection

Card catalog, enriched details, terms, history, and search. Pagination limit and field visibility are tier-dependent — see Tier Access above.

GET /cards

Paginated card catalog with filters. Returns up to 100 cards per page with structured metadata. Supports offset/limit pagination.

Parameter	Type	Required	Description
`q`	string (query)	No	Free-text search across card name, issuer, and description
`issuer`	string (query)	No	Filter by issuer (e.g. "Chase", "American Express")
`card_type`	string (query)	No	Filter by type: travel, cashback, business, student, hotel, airline, secured
`tag`	string (query)	No	Filter by tag (e.g. "balance_transfer", "no_foreign_fee", "lounge_access")
`network`	string (query)	No	Filter by network: Visa, Mastercard, Amex
`max_annual_fee`	integer (query)	No	Maximum annual fee in dollars
`offset`	integer (query)	No	Pagination offset (default 0)
`limit`	integer (query)	No	Results per page, 1-100 (default 20)
`sort_by`	string (query)	No	Sort field: card_name, annual_fee, issuer (default card_name)
`sort_order`	string (query)	No	asc or desc (default asc)

Request

GET /api/v1/cards?card_type=travel&max_annual_fee=300&limit=5

Response

{
  "success": true,
  "data": {
    "cards": [
      {
        "card_id": 42,
        "card_name": "Chase Sapphire Preferred Card",
        "issuer": "Chase",
        "network": "Visa",
        "card_type": "travel",
        "annual_fee": 95,
        "rewards_summary": "3x dining, 2x travel, 1x other",
        "tags": ["travel", "dining", "no_foreign_fee"]
      },
      ...
    ],
    "pagination": {
      "offset": 0,
      "limit": 5,
      "total": 53,
      "has_more": true,
      "next_cursor": "eyJpZCI6IDQ3fQ=="
    }
  },
  "metadata": {...}
}

GET /cards/{card_id}

Enriched card detail with structured nested objects for rewards, benefits, sign-on bonus, and terms. Single response contains everything needed to display full card information.

Parameter	Type	Required	Description
`card_id`	integer (path)	Yes	Card ID (from catalog or search results)

Request

GET /api/v1/cards/42

Response

{
  "success": true,
  "data": {
    "card_id": 42,
    "card_name": "Chase Sapphire Preferred Card",
    "issuer": "Chase",
    "network": "Visa",
    "card_type": "travel",
    "tags": ["travel", "dining", "no_foreign_fee"],
    "annual_fee": 95,
    "credit_score_needed": "good",
    "rewards": {
      "structure_text": "3x dining, 2x travel, 1x other",
      "multipliers": {"dining": 3.0, "travel": 2.0, "base": 1.0},
      "points_program_key": "chase_ur",
      "portal_cpp": 1.25
    },
    "benefits": {
      "annual_credits_value": 50,
      "annual_credits": [
        {"name": "Hotel Credit", "value": 50, "frequency": "annual"}
      ],
      "one_time_benefits": [],
      "key_benefits_text": "Trip cancellation insurance, no foreign transaction fees..."
    },
    "sign_on_bonus": {
      "amount": 60000,
      "type": "points",
      "spend_requirement": 4000,
      "time_period_months": 3,
      "description": "Earn 60,000 points after $4,000 in 3 months"
    },
    "terms": {
      "purchase_apr": "21.49%-28.49% Variable",
      "penalty_apr": "Up to 29.99%",
      "late_fee": "Up to $40",
      "cash_advance_fee": "Either $10 or 5%",
      "foreign_transaction_fee": "None",
      "balance_transfer_apr": "21.49%-28.49%",
      "grace_period_days": 21
    },
    "urls": {
      "apply_url": "https://...",
      "product_page_url": null
    },
    "data_quality": {
      "last_verified": "2026-05-10",
      "is_active": true
    }
  },
  "metadata": {...}
}

GET /cards/{card_id}/terms

Standalone terms endpoint for Schumer Box data (APR, penalties, fees). Same data is also inlined in the enriched card detail above.

Parameter	Type	Required	Description
`card_id`	integer (path)	Yes	Card ID

Request

GET /api/v1/cards/42/terms

Response

{
  "success": true,
  "data": {
    "card_id": 42,
    "card_name": "Chase Sapphire Preferred",
    "issuer": "Chase",
    "purchase_apr": "21.49%-28.49%",
    "cash_advance_apr": "29.49%",
    "penalty_apr": "29.99%",
    "balance_transfer_apr": "21.49%-28.49%",
    "late_fee": "Up to $40",
    "returned_payment_fee": "Up to $40",
    "cash_advance_fee": "$10 or 5%",
    "foreign_transaction_fee": "None",
    "promotional_apr": null,
    "promo_apr_months": null,
    "grace_period_days": "21",
    "last_extracted_at": "2026-04-24T...",
    "extraction_source": "gemini_grounding"
  },
  "metadata": {...}
}

GET /cards/{card_id}/history

Change history for a specific card. Returns chronological diffs for tracked fields (fees, APRs, benefits).

Parameter	Type	Required	Description
`card_id`	integer (path)	Yes	Card ID
`field`	string (query)	No	Filter by field (e.g. `annual_fee`, `purchase_apr`)
`since`	string (query)	No	ISO date (e.g. `2026-01-01`)

Request

GET /api/v1/cards/42/history?field=annual_fee&since=2026-01-01

Response

{
  "card_id": 42,
  "count": 1,
  "changes": [
    {
      "table": "popular_cards",
      "field": "annual_fee",
      "old_value": "95",
      "new_value": "150",
      "detected_at": "2026-03-15T...",
      "source": "weekly_batch_job"
    }
  ]
}

GET /cards/changes

Bulk changelog feed across all cards. Monitor fee increases, benefit removals, or rewards structure changes.

Parameter	Type	Required	Description
`since`	string (query)	Yes	ISO date (e.g. `2026-04-01`)
`fields`	string (query)	No	Comma-separated field names (e.g. `annual_fee,purchase_apr`)

Request

GET /api/v1/cards/changes?since=2026-04-01&fields=annual_fee,penalty_apr

Response

{
  "since": "2026-04-01",
  "count": 3,
  "changes": [
    {
      "card_id": 42,
      "table": "popular_cards",
      "field": "annual_fee",
      "old_value": "95",
      "new_value": "150",
      "detected_at": "2026-04-15T...",
      "source": "weekly_batch_job"
    },
    ...
  ]
}

POST /cards/search

Filtered + ranked card discovery. Returns scored results based on spending alignment, fee value, purpose match, and sign-on bonus. All filters optional.

Field	Type	Required	Description
`card_type`	string	No	Card type: travel, cashback, balance_transfer, business, student, hotel, airline
`max_annual_fee`	integer	No	Maximum annual fee in dollars
`issuer`	string	No	Filter by issuer
`spending`	object	No	Monthly spending by category for ranking
`credit_tier`	string	No	poor, fair, good, or excellent
`max_results`	integer	No	1-20 results (default 5)

Request

{
  "card_type": "balance_transfer",
  "max_annual_fee": 100,
  "credit_tier": "good",
  "max_results": 5
}

Response

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "card_name": "Citi Simplicity Card",
        "card_id": 88,
        "issuer": "Citi",
        "annual_fee": 0,
        "card_type": "balance_transfer",
        "match_score": 0.92,
        "reasoning": "0% intro APR for 21 months...",
        "rewards_structure": "No rewards",
        "sign_on_bonus": null,
        "apply_url": "https://..."
      },
      ...
    ],
    "total_found": 5,
    "filters_applied": {
      "card_type": "balance_transfer",
      "max_annual_fee": 100
    }
  },
  "metadata": {...}
}

Intelligence Collection

Computation and decision endpoints. All support ?mode=fast|verbose. Fast mode is deterministic (<100ms); verbose adds AI-generated narrative (3-5s).

POST /intelligence/compare

Compare 2-3 cards side-by-side with fees, rewards, net value, and break-even analysis. Add ?mode=verbose for AI-generated winner and narrative.

Field	Type	Required	Description
`card_names`	array[string]	Yes	2-3 card names to compare
`params.spending`	object	No	Monthly spending by category
`params.primary_goal`	string	No	Optimization goal
`params.credit_tier`	string	No	poor, fair, good, or excellent
`params.benefit_selections`	array	No	Benefit keys the user uses (100%/0% model)

Request

POST /api/v1/intelligence/compare?mode=fast

{
  "card_names": [
    "Chase Sapphire Preferred",
    "Capital One Venture X"
  ],
  "params": {
    "spending": {"dining": 400, "travel": 500, "groceries": 300},
    "primary_goal": "travel",
    "credit_tier": "excellent"
  }
}

Response

{
  "success": true,
  "data": {
    "comparison_table": [
      {
        "card_name": "Chase Sapphire Preferred",
        "annual_fee": 95,
        "net_value": 188,
        "total_rewards": 198,
        "points_program_key": "chase_ur",
        "portal_cpp": 1.25,
        "rewards_by_category": {"dining": 180, "travel": 120, ...},
        "break_even": {"status": "spending_required"}
      },
      ...
    ],
    "spending_source": "user_provided",
    "assumptions": {"redemption_rate": 1.0, "point_value": 0.01}
  },
  "metadata": {"mode": "fast", ...}
}

POST /intelligence/recommend

Get the best card recommendations for a spending category. From the full market, or from an existing portfolio. Add ?mode=verbose for AI narrative.

Field	Type	Required	Description
`category`	string	Yes	Spending category: dining, travel, groceries, gas, etc.
`portfolio_card_names`	array[string]	No	If provided, recommend from portfolio only
`params.spending`	object	No	Monthly spending by category
`params.credit_tier`	string	No	Filter by credit tier
`params.primary_goal`	string	No	Optimization goal

Request

{
  "category": "dining",
  "params": {
    "spending": {"dining": 600, "groceries": 400},
    "credit_tier": "excellent",
    "primary_goal": "cashback"
  }
}

Response

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "card_name": "American Express Gold Card",
        "issuer": "American Express",
        "annual_fee": 250,
        "net_value": 380,
        "points_program_key": "amex_mr",
        "portal_cpp": 1.1,
        "rewards_structure": "4x dining, 4x groceries..."
      }
    ],
    "category": "dining",
    "spending_source": "user_provided",
    "total_candidates": 8
  },
  "metadata": {"mode": "fast", ...}
}

POST /intelligence/value

Calculate the financial value and break-even point of a credit card. Returns first-year value (with sign-on bonus), ongoing annual value, and a WORTH_IT / NOT_WORTH_IT verdict.

Field	Type	Required	Description
`card_name`	string	No	Card name for DB lookup
`annual_fee`	number	No	Annual fee ($). Pulled from DB if card_name provided.
`spending`	object	No	Monthly spending by category
`benefit_selections`	array	No	Benefit keys the user uses (100%/0% model)

Request

{
  "card_name": "Chase Sapphire Preferred",
  "spending": {
    "dining": 500, "travel": 300, "groceries": 400
  },
  "benefit_selections": ["dining", "travel"]
}

Response

{
  "success": true,
  "data": {
    "first_year": {
      "total_value": 1250,
      "net_value": 1155,
      "sign_on_bonus_value": 750,
      "benefits_utilized": 0,
      "total_rewards": 500
    },
    "ongoing_annual": {
      "total_value": 500,
      "net_value": 405
    },
    "break_even": {"monthly_spend_needed": 350},
    "rewards_by_category": {"dining": 180, "travel": 72, "groceries": 48},
    "verdict": "WORTH_IT",
    "spending_source": "user_provided",
    "points_program_key": "chase_ur",
    "portal_cpp": 1.25
  },
  "metadata": {...}
}

POST /intelligence/renewal

Check if a card is worth keeping at annual fee renewal. Returns RENEW, DOWNGRADE, or CANCEL_AND_REPLACE. Add ?mode=verbose for retention tips and timing guidance.

Field	Type	Required	Description
`card_name`	string	Yes	Card name to evaluate
`params.spending`	object	No	Monthly spending by category
`params.primary_goal`	string	No	Optimization goal
`params.credit_tier`	string	No	poor, fair, good, or excellent
`acquired_date`	string	No	Date card was acquired (`YYYY-MM-DD`)
`benefit_selections`	array	No	Benefit keys the user uses

Request

POST /api/v1/intelligence/renewal?mode=fast

{
  "card_name": "Chase Sapphire Preferred",
  "acquired_date": "2024-06-15",
  "params": {
    "spending": {"dining": 400, "travel": 300, "groceries": 500},
    "primary_goal": "travel"
  },
  "benefit_selections": ["dining", "travel"]
}

Response

{
  "success": true,
  "data": {
    "verdict": "RENEW",
    "year2_net_value": 120.50,
    "confidence": "high",
    "points_program_key": "chase_ur",
    "portal_cpp": 1.25,
    "spending_source": "user_provided",
    "downgrade_options": [...],
    "replacement_options": [...],
    "thresholds_used": {"cancel": -100, "keep": 50}
  },
  "metadata": {"mode": "fast", ...}
}

POST /intelligence/merchant/best-card

Find the best card from your portfolio for a purchase at a specific merchant. Auto-detects spending category (e.g. Starbucks → dining) and ranks cards by reward value.

Field	Type	Required	Description
`merchant`	string	Yes	Merchant name (e.g. "Starbucks", "Delta Air Lines")
`amount`	number	No	Purchase amount in dollars (default 100)
`portfolio`	array[string]	Yes	Card names in your portfolio

Request

{
  "merchant": "Starbucks",
  "amount": 35,
  "portfolio": [
    "Chase Sapphire Reserve",
    "Amex Gold",
    "Citi Double Cash"
  ]
}

Response

{
  "success": true,
  "data": {
    "recommended_card": "American Express Gold Card",
    "category_detected": "dining",
    "category_method": "exact",
    "reason": "Starbucks codes as dining — Amex Gold 4x vs CSR 3x vs Citi DC 2%",
    "earnings_comparison": [
      {
        "card": "American Express Gold Card",
        "multiplier": "4x",
        "points_earned": 140,
        "program": "Membership Rewards",
        "estimated_value": "$2.10"
      },
      ...
    ]
  },
  "metadata": {...}
}

POST /intelligence/merchant/benefits

Check if any cards in your portfolio have credits or benefits at a specific merchant.

Field	Type	Required	Description
`merchant`	string	Yes	Merchant name (e.g. "Saks Fifth Avenue", "Uber")
`portfolio`	array[string]	Yes	Card names in your portfolio

Request

{
  "merchant": "Saks Fifth Avenue",
  "portfolio": ["Amex Platinum", "Chase Sapphire Reserve"]
}

Response

{
  "success": true,
  "data": {
    "matching_benefits": [
      {
        "card": "The Platinum Card from American Express",
        "benefit_key": "saks",
        "name": "Saks Fifth Avenue Credit",
        "value": 100,
        "frequency": "semi-annual",
        "schedule": "$50 Jan-Jun, $50 Jul-Dec",
        "note": "Your Amex Platinum has a $100 Saks credit."
      }
    ],
    "earning_recommendation": {
      "best_card": "The Platinum Card from American Express",
      "multiplier": "1x",
      "note": "Use Amex Platinum to combine with the credit."
    }
  },
  "metadata": {...}
}

Portfolio Collection

User-specific portfolio management: analyze your cards, generate redemption playbooks, and manage points balances.

POST /portfolio/analyze

Analyze 1-10 credit cards for total value, per-card verdicts (KEEP/OPTIMIZE/CANCEL), and break-even analysis. Add ?mode=verbose for AI narrative.

Field	Type	Required	Description
`cards`	array	Yes	1-10 cards, each with `card_name` and optional `annual_fee`
`params.spending`	object	No	Monthly spending by category (dining, travel, groceries, gas, streaming, shopping, other)
`params.primary_goal`	string	No	travel, cashback, build_credit, business, or balance_transfer
`params.credit_tier`	string	No	poor, fair, good, or excellent
`params.issuer_preferences`	array	No	Boost/de-boost issuers, e.g. `[{"issuer": "Chase", "weight": 1.5}]`
`params.point_balances`	array	No	Rewards balances, e.g. `[{"program": "chase_ur", "balance": 150000}]`
`params.benefit_selections`	array	No	Benefit keys the user uses (100%/0% model). If omitted, 50% utilization assumed.

Request

POST /api/v1/portfolio/analyze?mode=fast

{
  "cards": [
    {"card_name": "Chase Sapphire Preferred", "annual_fee": 95},
    {"card_name": "American Express Gold Card", "annual_fee": 250}
  ],
  "params": {
    "spending": {
      "dining": 500, "travel": 300,
      "groceries": 400, "gas": 100,
      "streaming": 30, "shopping": 200, "other": 150
    },
    "primary_goal": "travel",
    "point_balances": [
      {"program": "chase_ur", "balance": 150000},
      {"program": "amex_mr", "balance": 80000}
    ],
    "benefit_selections": ["uber", "dining", "travel", "saks"]
  }
}

Response

{
  "success": true,
  "data": {
    "card_details": [
      {
        "card_name": "Chase Sapphire Preferred",
        "net_value": 188,
        "verdict": "KEEP",
        "points_program_key": "chase_ur",
        "portal_cpp": 1.25,
        "rewards_by_category": {"dining": 180, "travel": 72, ...},
        "break_even": {"status": "spending_required"}
      },
      ...
    ],
    "portfolio_summary": {
      "total_annual_fees": 345,
      "net_value": 434,
      "total_rewards": 444
    },
    "spending_source": "user_provided"
  },
  "metadata": {"mode": "fast", ...}
}

POST /portfolio/points-playbook

Generate a points redemption playbook. Returns cashback earning estimates, points-at-risk warnings, and AI-generated per-program strategies with transfer partner suggestions.

Field	Type	Required	Description
`cards`	array[string]	Yes	1-10 card names to analyze
`point_balances`	array	No	Point/miles balances: `[{"program_key": "chase_ur", "balance": 70000}]`
`spending`	object	No	Monthly spending by category

Request

{
  "cards": ["Chase Sapphire Reserve", "American Express Gold Card"],
  "point_balances": [
    {"program_key": "chase_ur", "balance": 70000},
    {"program_key": "amex_mr", "balance": 50000}
  ],
  "spending": {"dining": 500, "travel": 300, "groceries": 400}
}

Response

{
  "success": true,
  "data": {
    "cashback_earning": {
      "total_annual_cashback": 156.00,
      "cards": ["Citi Double Cash"],
      "summary": "You earn ~$156/year in cashback"
    },
    "points_at_risk": [
      {"program": "chase_ur", "warning": "Cancel CSR and you lose 70K points"}
    ],
    "points_playbook": [
      {
        "program": "Chase Ultimate Rewards",
        "balance": 70000,
        "strategy": "Transfer to Hyatt for 2 nights...",
        "best_transfer": "World of Hyatt (1:1)"
      }
    ]
  },
  "metadata": {...}
}

GET /portfolio/points/balances

Read your stored points/miles balances.

Request

GET /api/v1/portfolio/points/balances

Response

{
  "success": true,
  "data": {
    "balances": [
      {"program_key": "chase_ur", "balance": 150000, "updated_at": "2026-05-20T..."},
      {"program_key": "amex_mr", "balance": 80000, "updated_at": "2026-05-18T..."}
    ]
  }
}

POST /portfolio/points/balances

Batch upsert points balances. Creates or updates entries for each program key.

Request

{
  "balances": [
    {"program_key": "chase_ur", "balance": 175000},
    {"program_key": "amex_mr", "balance": 92000}
  ]
}

Response

{
  "success": true,
  "data": {"updated": 2, "message": "Balances saved"}
}

DELETE /portfolio/points/balances/{program_key}

Remove a stored points balance.

Request

DELETE /api/v1/portfolio/points/balances/chase_ur

Response

{
  "success": true,
  "data": {"deleted": "chase_ur"}
}

GET /portfolio/points/summary

Get total value of all your stored points balances, calculated using portal CPP rates.

Request

GET /api/v1/portfolio/points/summary

Response

{
  "success": true,
  "data": {
    "total_value_usd": 2755.00,
    "programs": [
      {"program_key": "chase_ur", "balance": 150000, "cpp": 1.25, "value_usd": 1875.00},
      {"program_key": "amex_mr", "balance": 80000, "cpp": 1.1, "value_usd": 880.00}
    ]
  }
}

Reference Collection

Static lookup data for points programs, transfer partners, and benefit categories. No user-specific state.

GET /reference/programs

List all verified, active points programs with portal CPP, transfer partners, and currency names.

Request

GET /api/v1/reference/programs

Response

{
  "success": true,
  "data": {
    "count": 11,
    "programs": [
      {
        "program_key": "chase_ur",
        "program_name": "Chase Ultimate Rewards",
        "currency_name": "Ultimate Rewards points",
        "portal_cpp": 1.25,
        "points_expire": false,
        "transfer_partners": {
          "airlines": ["United", "Southwest", "British Airways", ...],
          "hotels": ["Hyatt", "IHG", "Marriott"]
        }
      },
      ...
    ]
  }
}

GET /reference/programs/{program_key}

Get a single program's details including transfer partners, portal CPP, and currency info.

Parameter	Type	Required	Description
`program_key`	string (path)	Yes	Program key (e.g. `chase_ur`, `amex_mr`, `cap1_miles`)

Request

GET /api/v1/reference/programs/amex_mr

Response

{
  "success": true,
  "data": {
    "program_key": "amex_mr",
    "program_name": "Amex Membership Rewards",
    "currency_name": "Membership Rewards points",
    "portal_cpp": 1.1,
    "points_expire": false,
    "transfer_partners": {
      "airlines": ["Delta", "ANA", "Singapore Airlines", ...],
      "hotels": ["Hilton", "Marriott", ...]
    }
  }
}

GET /reference/programs/{program_key}/history

CPP and transfer partner ratio change history for a points program. Track valuation trends over time.

Parameter	Type	Required	Description
`program_key`	string (path)	Yes	Program key
`since`	string (query)	No	ISO date (e.g. `2026-01-01`)

Request

GET /api/v1/reference/programs/chase_ur/history?since=2026-01-01

Response

{
  "program_key": "chase_ur",
  "count": 2,
  "changes": [
    {
      "field": "portal_cpp",
      "old_value": "1.25",
      "new_value": "1.50",
      "detected_at": "2026-02-01T...",
      "source": "transfer_partner_refresh"
    },
    ...
  ]
}

GET /reference/benefit-categories

Returns the benefit key registry — all valid keys for benefit_selections, grouped by category. Use this to discover which keys to pass in portfolio and renewal requests.

Request

GET /api/v1/reference/benefit-categories

Response

{
  "categories": [
    {
      "category": "dining_credit",
      "label": "Dining Credits",
      "keys": ["dining", "resy_dining"]
    },
    {
      "category": "lounge_access",
      "label": "Lounge Access",
      "keys": ["admirals_club", "united_club_membership"]
    },
    ...
  ],
  "all_keys": ["admirals_club", "airline_fee", "avis_budget", ...],
  "usage": {
    "benefit_selections": "Pass keys to portfolio/analyze or intelligence/renewal...",
    "benefit_categories_used": "Alternative: pass category names instead..."
  }
}

Platform Collection

System health, API usage, billing, and developer account management.

GET /platform/health

System health check. No authentication required. Returns service status, database connectivity, and card count.

Request

GET /api/v1/platform/health

Response

{
  "status": "healthy",
  "version": "1.0",
  "database": "connected",
  "cards_loaded": 148,
  "timestamp": "2026-05-24T14:30:00Z"
}

GET /platform/status

Detailed system status. Returns service health, total active cards, and optional points programs count.

Request

GET /api/v1/platform/status

Response

{
  "success": true,
  "data": {
    "status": "operational",
    "database": "connected",
    "active_cards": 148,
    "points_programs": 11,
    "api_version": "v1"
  }
}

GET /platform/usage

Your current API usage for the billing period. Per-endpoint breakdown, by-channel split (REST vs MCP), and rate limit info.

Request

GET /api/v1/platform/usage

Response

{
  "success": true,
  "data": {
    "period": "2026-05",
    "tier": "pro",
    "calls_used": 3427,
    "calls_limit": 10000,
    "calls_remaining": 6573,
    "by_endpoint": {
      "/api/v1/cards": 890,
      "/api/v1/intelligence/compare": 542,
      "/api/v1/portfolio/analyze": 1205,
      ...
    },
    "by_channel": {
      "rest": 2895,
      "mcp": 532
    },
    "rate_limit": {
      "requests_per_minute": 120,
      "monthly_limit": 10000
    }
  }
}

POST /platform/billing/checkout

Create a Stripe Checkout session for upgrading to a paid tier. Returns a redirect URL.

Response

{
  "checkout_url": "https://checkout.stripe.com/...",
  "session_id": "cs_live_..."
}

POST /platform/billing/portal

Open Stripe Customer Portal for managing subscription, payment method, and invoices.

Response

{
  "portal_url": "https://billing.stripe.com/..."
}

Try all endpoints interactively in Swagger UI →

Authentication

Base URL

API Collections

Fast vs Verbose Mode

Response Envelope

Tier-Based Data Access

Endpoint Limits by Tier

Field Visibility — Catalog (GET /cards)

Field Visibility — Enriched Detail (GET /cards/{id})

Field Visibility — Terms (GET /cards/{id}/terms)

Field Visibility — Search (POST /cards/search)

Tier-Restricted Response Signals

Tier-Gated Error Responses

Cards Collection

GET /cards

GET /cards/{card_id}

GET /cards/{card_id}/terms

GET /cards/{card_id}/history

GET /cards/changes

POST /cards/search

Intelligence Collection

POST /intelligence/compare

POST /intelligence/recommend

POST /intelligence/value

POST /intelligence/renewal

POST /intelligence/merchant/best-card

POST /intelligence/merchant/benefits

Portfolio Collection

POST /portfolio/analyze

POST /portfolio/points-playbook

GET /portfolio/points/balances

POST /portfolio/points/balances

DELETE /portfolio/points/balances/{program_key}

GET /portfolio/points/summary

Reference Collection

GET /reference/programs

GET /reference/programs/{program_key}

GET /reference/programs/{program_key}/history

GET /reference/benefit-categories

Platform Collection

GET /platform/health

GET /platform/status

GET /platform/usage

POST /platform/billing/checkout

POST /platform/billing/portal

Field Visibility — Catalog (`GET /cards`)

Field Visibility — Enriched Detail (`GET /cards/{id}`)

Field Visibility — Terms (`GET /cards/{id}/terms`)

Field Visibility — Search (`POST /cards/search`)