API Reference

Complete reference for the CardAPI REST API. All endpoints return JSON and require authentication.

Download Postman CollectionRate Limits & Quotas →OpenAPI Spec (JSON)

SDKs

Official SDKs are available on npm and PyPI. They handle authentication, serialization, and error handling out of the box.

JavaScript / TypeScriptnpm →
npm install @cardapi/client
Usage
import { CardAPI } from "@cardapi/client";

const client = new CardAPI("your_api_key");
const cards = await client.getCards({ country: "US" });
PythonPyPI →
pip install cardapi
Usage
from cardapi import CardAPI

client = CardAPI("your_api_key")
cards = client.get_cards(country="US")

Authentication

HEADERAuthorization: Bearer <api_key>

All API requests require authentication via a Bearer token in the Authorization header. Get your API key from the dashboard. Keys use the ck_live_ prefix for production and ck_test_ for sandbox.

Response
// Authenticated request
{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "rate_limit_remaining": 4999
  }
}

// Unauthenticated request
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Cards

GET/v1/cards

List all credit cards. Returns paginated results with basic card information. Use query parameters to filter by issuer, country, or category.

Parameters
issuerstringFilter by issuer slug (e.g. chase, amex)
countrystringFilter by country code: US or CA
categorystringFilter by reward category (e.g. dining, groceries)
limitintegerResults per page (default: 25, max: 100)
offsetintegerPagination offset
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/cards" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "id": "amex-gold",
      "name": "American Express Gold Card",
      "issuer": "amex",
      "network": "amex",
      "annual_fee": 250,
      "country": "US",
      "url": "/v1/cards/amex-gold"
    }
  ],
  "meta": {
    "total": 412,
    "limit": 25,
    "offset": 0
  }
}
GET/v1/cards/:id

Get full details for a single credit card, including reward rates, benefits, application criteria, and signup bonus information.

Parameters
idstringrequiredCard slug identifier (e.g. amex-gold, chase-sapphire-preferred)
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/cards/:id" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": {
    "id": "amex-gold",
    "name": "American Express Gold Card",
    "issuer": "amex",
    "network": "amex",
    "annual_fee": 250,
    "country": "US",
    "foreign_transaction_fee": 0,
    "signup_bonus": {
      "amount": "60,000",
      "currency": "MR points",
      "spend_requirement": 6000,
      "time_period_months": 6
    },
    "reward_rates": [
      { "category": "dining", "rate": 4, "type": "multiplier" },
      { "category": "groceries", "rate": 4, "type": "multiplier", "cap": 25000 },
      { "category": "flights", "rate": 3, "type": "multiplier" },
      { "category": "other", "rate": 1, "type": "multiplier" }
    ],
    "benefits": [
      "Dining credit: $120/year",
      "Uber Cash: $120/year",
      "Hotel Collection: $100 credit"
    ],
    "credit_score_min": 700,
    "is_business": false,
    "updated_at": "2026-03-20T04:00:00Z"
  }
}
GET/v1/cards/best

Get the best cards for a specific spending category. Returns cards ranked by reward rate, with optional country filter.

Parameters
categorystringrequiredSpending category (dining, groceries, gas, travel, etc.)
countrystringCountry code: US or CA
limitintegerNumber of results (default: 10)
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/cards/best" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "id": "amex-gold",
      "name": "American Express Gold Card",
      "rate": 4,
      "type": "multiplier",
      "annual_fee": 250
    },
    {
      "id": "citi-custom-cash",
      "name": "Citi Custom Cash Card",
      "rate": 5,
      "type": "cashback_percent",
      "annual_fee": 0,
      "cap": 500
    }
  ]
}
GET/v1/cards/:id/perks

Returns companion perks for a specific card, including hotel elite status, TSA PreCheck credits, airline perks, and lounge access.

Parameters
idstringrequiredCard slug identifier (e.g. amex-platinum, chase-sapphire-reserve)
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/cards/:id/perks" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "name": "Global Entry / TSA PreCheck Credit",
      "value": 100,
      "frequency": "every 4 years",
      "category": "travel"
    },
    {
      "name": "Priority Pass Lounge Access",
      "value": null,
      "frequency": "unlimited",
      "category": "lounge"
    },
    {
      "name": "Marriott Bonvoy Gold Elite Status",
      "value": null,
      "frequency": "annual",
      "category": "hotel_status"
    }
  ]
}
GET/v1/cards/:id/credits

Returns statement credits for a specific card, including airline fee credits, Uber Cash, streaming credits, and dining credits with amounts and periods.

Parameters
idstringrequiredCard slug identifier (e.g. amex-gold, amex-platinum)
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/cards/:id/credits" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "name": "Dining Credit",
      "amount": 120,
      "period": "annual",
      "description": "$10/month at Grubhub, The Cheesecake Factory, Goldbelly, Wine.com, and Five Guys"
    },
    {
      "name": "Uber Cash",
      "amount": 120,
      "period": "annual",
      "description": "$10/month in Uber Cash for Uber Eats orders or Uber rides in the US"
    },
    {
      "name": "Airline Fee Credit",
      "amount": 200,
      "period": "annual",
      "description": "Up to $200 in statement credits per calendar year for incidental fees with one selected airline"
    }
  ]
}

Issuers

GET/v1/issuers

List all supported card issuers with card counts.

Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/issuers" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "id": "chase",
      "name": "Chase",
      "country": "US",
      "card_count": 45,
      "url": "/v1/issuers/chase"
    },
    {
      "id": "amex",
      "name": "American Express",
      "country": "US",
      "card_count": 38,
      "url": "/v1/issuers/amex"
    }
  ]
}
GET/v1/issuers/:id

Get details for a specific issuer, including all their cards.

Parameters
idstringrequiredIssuer slug (e.g. chase, amex, capital-one)
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/issuers/:id" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": {
    "id": "chase",
    "name": "Chase",
    "country": "US",
    "website": "https://www.chase.com",
    "cards": [
      { "id": "chase-sapphire-preferred", "name": "Chase Sapphire Preferred" },
      { "id": "chase-sapphire-reserve", "name": "Chase Sapphire Reserve" },
      { "id": "chase-freedom-unlimited", "name": "Chase Freedom Unlimited" }
    ]
  }
}

Categories

GET/v1/categories

List all spending categories tracked by CardAPI. Use these slugs when querying reward rates.

Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/categories" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    { "id": "dining", "name": "Dining", "description": "Restaurants, bars, cafes" },
    { "id": "groceries", "name": "Groceries", "description": "Supermarkets, grocery stores" },
    { "id": "gas", "name": "Gas", "description": "Gas stations, EV charging" },
    { "id": "travel", "name": "Travel", "description": "Hotels, flights, car rentals" },
    { "id": "flights", "name": "Flights", "description": "Airlines, airfare" },
    { "id": "hotels", "name": "Hotels", "description": "Hotel bookings" },
    { "id": "streaming", "name": "Streaming", "description": "Netflix, Spotify, etc." },
    { "id": "online_shopping", "name": "Online Shopping", "description": "Amazon, ecommerce" },
    { "id": "transit", "name": "Transit", "description": "Trains, buses, rideshare" },
    { "id": "other", "name": "Other", "description": "All other purchases" }
  ]
}

Transfer Partners

GET/v1/transfer-partners

List all loyalty program transfer partners with transfer ratios. Filter by card or program.

Parameters
card_idstringFilter by card slug
programstringFilter by loyalty program (e.g. aeroplan, hyatt)
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/transfer-partners" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "from_program": "Amex Membership Rewards",
      "to_program": "Aeroplan",
      "ratio": "1:1",
      "transfer_time": "instant",
      "cards": ["amex-gold", "amex-platinum"]
    },
    {
      "from_program": "Chase Ultimate Rewards",
      "to_program": "World of Hyatt",
      "ratio": "1:1",
      "transfer_time": "instant",
      "cards": ["chase-sapphire-preferred", "chase-sapphire-reserve"]
    }
  ]
}

Reward Valuations

GET/v1/reward-valuations

Returns point and mile cents-per-point (CPP) valuations for all reward currencies, including Chase Ultimate Rewards, Amex Membership Rewards, Citi ThankYou Points, and more. Useful for calculating effective earn rates across cards.

Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/reward-valuations" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "currency_name": "Chase Ultimate Rewards",
      "currency_code": "UR",
      "cpp_cash": 1.0,
      "cpp_travel_portal": 1.5,
      "cpp_transfer": 2.0,
      "cpp_recommended": 2.0
    },
    {
      "currency_name": "Amex Membership Rewards",
      "currency_code": "MR",
      "cpp_cash": 0.6,
      "cpp_travel_portal": 1.0,
      "cpp_transfer": 2.0,
      "cpp_recommended": 2.0
    },
    {
      "currency_name": "Citi ThankYou Points",
      "currency_code": "TYP",
      "cpp_cash": 1.0,
      "cpp_travel_portal": 1.0,
      "cpp_transfer": 1.7,
      "cpp_recommended": 1.7
    }
  ]
}

Application Rules

GET/v1/application-rules

List all known application rules and restrictions by issuer. Includes velocity limits, lifetime rules, and product change restrictions.

Parameters
issuerstringFilter by issuer slug
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/application-rules" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "issuer": "chase",
      "rule": "5/24",
      "description": "Cannot be approved if you have opened 5+ new credit cards in the last 24 months (any issuer)",
      "applies_to": "all personal cards"
    },
    {
      "issuer": "amex",
      "rule": "once-per-lifetime",
      "description": "Signup bonus is limited to once per lifetime per card product",
      "applies_to": "all cards with signup bonus"
    },
    {
      "issuer": "citi",
      "rule": "8/65",
      "description": "Limited to 1 application per 8 days and 2 applications per 65 days",
      "applies_to": "all cards"
    }
  ]
}

Product Changes

GET/v1/product-changes

Returns product change paths showing which cards can be upgraded or downgraded to which other cards. Useful for understanding card retention options and avoiding annual fees. Filter by issuer to narrow results.

Parameters
issuerstringFilter by issuer slug (e.g. chase, amex, citi)
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/product-changes" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "from_card": "chase-sapphire-preferred",
      "from_card_name": "Chase Sapphire Preferred",
      "to_card": "chase-freedom-unlimited",
      "to_card_name": "Chase Freedom Unlimited",
      "direction": "downgrade",
      "issuer": "chase",
      "notes": "Can product change after 12 months of card membership"
    },
    {
      "from_card": "chase-sapphire-preferred",
      "from_card_name": "Chase Sapphire Preferred",
      "to_card": "chase-sapphire-reserve",
      "to_card_name": "Chase Sapphire Reserve",
      "direction": "upgrade",
      "issuer": "chase",
      "notes": "Upgrade eligible after 12 months; no new signup bonus"
    }
  ]
}

Webhooks

POST/v1/webhooks

Create a webhook to receive notifications when card data changes. Enterprise plan only. Supports card.updated, card.created, and card.deleted events.

Parameters
urlstringrequiredThe HTTPS URL to receive webhook events
eventsstring[]requiredEvent types: card.updated, card.created, card.deleted
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \ \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "id": "wh_abc123",
    "url": "https://your-app.com/webhooks/cardapi",
    "events": ["card.updated", "card.created"],
    "secret": "whsec_xxx",
    "created_at": "2026-03-20T04:00:00Z"
  }
}