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 { CardDB } from "@cardapi/client";

const client = new CardDB({ apiKey: "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.

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

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

Create an account and get a free-tier API key. Rate limited by IP (5/hour, 10/day) to prevent abuse.

Parameters
emailstringrequiredAccount email address
passwordstringrequiredAccount password
Response
{
  "api_key": "ck_live_xxxxxxxxxxxxxxxx",
  "tier": "free"
}
POST/v1/auth/keys

Create an additional API key for your account. Maximum 5 active keys per account.

Response
{
  "api_key": "ck_live_xxxxxxxxxxxxxxxx"
}
GET/v1/auth/usage

Check your current daily and monthly usage against your tier's limits.

Response
{
  "tier": "starter",
  "daily_used": 128,
  "daily_limit": 500,
  "monthly_used": 3402,
  "monthly_limit": 15000
}
POST/v1/auth/upgrade

Upgrade your account to a paid tier. Returns a Stripe Checkout URL to complete payment.

Parameters
tierstringrequiredTarget tier: starter, pro, or enterprise
Response
{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_xxx"
}

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/search

Full-text search across card names and issuers.

Parameters
qstringrequiredSearch query (max 200 characters)
limitintegerResults per page (default: 20, max: 100)
offsetintegerPagination offset
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/cards/search" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    { "id": "chase-sapphire-preferred", "name": "Chase Sapphire Preferred", "issuer": "chase" }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
GET/v1/cards/compare

Compare 2-5 cards side by side in a single response.

Parameters
slugsstringrequiredComma-separated card slugs (2-5)
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/cards/compare" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    { "id": "chase-sapphire-preferred", "name": "Chase Sapphire Preferred", "annual_fee": 95 },
    { "id": "amex-gold", "name": "American Express Gold Card", "annual_fee": 250 }
  ]
}
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"
    }
  ]
}
GET/v1/cards/:id/history

Returns the change history for a card -- fee changes, signup bonus updates, and other tracked field changes over time. Pro plan and above.

Parameters
idstringrequiredCard slug identifier
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/cards/:id/history" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "field": "signup_bonus_value",
      "old_value": "60000",
      "new_value": "75000",
      "changed_at": "2026-05-01T00:00:00Z"
    }
  ]
}
GET/v1/cards/:id/transfers

Returns transfer partners for a specific card's reward currency. Pro plan and above.

Parameters
idstringrequiredCard slug identifier
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/cards/:id/transfers" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    { "to_program": "Aeroplan", "ratio": "1:1", "transfer_time": "instant" }
  ]
}

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" }
    ]
  }
}
GET/v1/issuers/:id/rules

Returns application rules and restrictions for a specific issuer (e.g. Chase's 5/24 rule).

Parameters
idstringrequiredIssuer slug (e.g. chase, amex)
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/issuers/:id/rules" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "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"
    }
  ]
}

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"
    }
  ]
}

Offer Changes

GET/v1/offers/notable

Recent notable offer changes across all tracked cards -- signup bonus increases, fee changes, and other detected updates. Pro plan and above.

Parameters
countrystringFilter by country code: US or CA
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/offers/notable" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "card_id": "amex-gold",
      "change_type": "signup_bonus_increase",
      "description": "Signup bonus increased from 60,000 to 75,000 points",
      "detected_at": "2026-05-01T00:00:00Z"
    }
  ]
}
GET/v1/offers/history

Full offer change history for a specific card. Pro plan and above.

Parameters
card_slugstringrequiredCard slug identifier
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/offers/history" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "change_type": "signup_bonus_increase",
      "description": "Signup bonus increased from 60,000 to 75,000 points",
      "detected_at": "2026-05-01T00:00:00Z"
    }
  ]
}

Stats

GET/v1/stats

Aggregate database statistics: card counts, issuer counts, and last update time.

Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": {
    "total_cards": 458,
    "published_cards": 448,
    "total_issuers": 39,
    "issuers_by_country": { "US": 25, "CA": 15 },
    "last_updated": "2026-07-10T19:17:43.292Z"
  }
}

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"
  }
}
GET/v1/webhooks

List all webhooks registered for your API key. Enterprise plan only.

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"
Response
{
  "data": [
    {
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "url": "https://your-app.com/webhooks/cardapi",
      "events": ["card.updated"],
      "is_active": true,
      "last_triggered_at": "2026-07-01T12:00:00Z",
      "failure_count": 0,
      "created_at": "2026-03-20T04:00:00Z"
    }
  ]
}
DELETE/v1/webhooks/:id

Delete a webhook. Enterprise plan only.

Parameters
idstringrequiredWebhook ID (UUID)
Example
Sign in to auto-fill your API key
curl "https://adaptable-dream-production-2fce.up.railway.app
/v1/webhooks/:id" \
  -H "Authorization: Bearer YOUR_API_KEY" \ \
  -X DELETE \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "success": true
}