{"openapi":"3.0.3","info":{"title":"CardAPI","version":"1.1.0","description":"Credit card data for the US and Canada: fees, reward rates, benefits, perks, statement credits, eligibility and offers. Every request except /v1/stats and /v1/auth/register needs an API key. Quotas are per account: every key on an account shares one daily and one monthly limit. Card fields depend on the plan: Free gets the basic fields and the top 3 reward rates; Starter adds full details, every rate, benefits, perks and statement credits; Pro adds spend bonuses, military benefits and the best-ever offer; Enterprise adds card art. Fields above your plan are left out of the response. Every authenticated response carries an X-CardAPI-Plan header naming the key's plan. 401, 403 and 429 errors add upgrade_url and docs_url; a 429 also says which plan and limit was hit (plan, limit, limit_value). Plans and the fields each returns: https://cardapi.dev/pricing.","termsOfService":"https://cardapi.dev/terms","contact":{"name":"CardAPI support","email":"support@cardapi.dev","url":"https://cardapi.dev/contact"},"license":{"name":"CardAPI Terms of Service","url":"https://cardapi.dev/terms#data"},"x-logo":{"url":"https://cardapi.dev/logo.svg","altText":"CardAPI","href":"https://cardapi.dev"}},"externalDocs":{"description":"CardAPI documentation","url":"https://cardapi.dev/docs"},"servers":[{"url":"https://api.cardapi.dev","description":"Production"}],"tags":[{"name":"Cards","description":"Card products: fees, reward rates, benefits, eligibility, history and comparisons."},{"name":"Issuers","description":"Card issuers in the US and Canada, and their application rules."},{"name":"Transfer Partners","description":"Points-to-partner transfer directory (Pro plan and above)."},{"name":"Application Rules","description":"Issuer application rules (for example 5/24)."},{"name":"Offers","description":"Welcome offer changes (Pro plan and above)."},{"name":"Meta","description":"Categories, reward valuations and database stats."},{"name":"Auth","description":"Sign-up links, keys, usage and plan upgrades."},{"name":"Webhooks","description":"Card change notifications (Enterprise plan)."},{"name":"System","description":"Health check."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key with 'Bearer ' prefix, e.g. 'Bearer ck_live_...'"}},"headers":{"X-CardAPI-Plan":{"description":"The plan of the API key that made the request: free, starter, pro or enterprise.","schema":{"type":"string","enum":["free","starter","pro","enterprise"]}}},"responses":{"BadRequest":{"description":"Invalid parameter or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, invalid or deactivated API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Your plan doesn't include this endpoint (forbidden; upgrade_url and docs_url say which plans do), or the account is suspended (account_suspended; contact support@cardapi.dev)","headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such card, issuer or webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Daily or monthly quota used up. Retry-After gives the seconds until the blocking window resets. The body names the plan and the limit hit (plan, limit, limit_value), what the next plan gives (message) and upgrade_url.","headers":{"Retry-After":{"description":"Seconds until the blocking window resets.","schema":{"type":"integer"}},"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServiceUnavailable":{"description":"CardAPI briefly couldn't check your key or usage. Retry-After is 30; this is not your quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable code, e.g. bad_request, unauthorized, forbidden, account_suspended, not_found, rate_limited, service_unavailable, timeout"},"message":{"type":"string"},"upgrade_url":{"type":"string","format":"uri","description":"On 401, 403 (forbidden) and 429: where to get a key or a plan that allows this request."},"docs_url":{"type":"string","format":"uri","description":"On 401, 403 (forbidden) and 429: the docs for this error."},"plan":{"type":"string","enum":["free","starter","pro","enterprise"],"description":"On 429: the plan whose limit was hit."},"limit":{"type":"string","enum":["daily","monthly"],"description":"On 429: the quota window that blocks the request."},"limit_value":{"type":"integer","description":"On 429: that window's call limit."}},"required":["code","message"]}},"required":["error"]},"CardIssuer":{"type":"object","description":"The card's issuer. `website` is on GET /v1/cards/{slug} only.","properties":{"slug":{"type":"string"},"name":{"type":"string"},"country":{"type":"string","enum":["US","CA"]},"logo_url":{"type":"string","nullable":true},"website":{"type":"string","nullable":true}}},"RewardRate":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"card_id":{"type":"string","format":"uuid"},"category_slug":{"type":"string","nullable":true,"description":"Label for the rate, unique on its card within a rotating quarter and built from the fields beside it, so the same rate has the same label on every card: <categories>[:<merchant>][@portal|@direct][#choice][~<tag>]. categories: the rate's `categories` joined by \"+\" in /v1/categories order (\"groceries+gas\"); a base rate is \"other\". :<merchant>: the merchant it is limited to, slugged (\"airlines:united-airlines\", \"other:best-buy\"). @portal / @direct: booking_channel issuer_portal / direct (\"travel@portal\"). #choice: one of a pick-your-category group (\"dining#choice\"). ~<tag>: only when two rates of one card would otherwise share a label, e.g. \"airlines:united-airlines~3x\"; a tag can change when the card's other rates change. Match on `categories`, `merchant`, `booking_channel` and `choice_group`, not by parsing the label."},"categories":{"type":"array","items":{"type":"string"},"description":"Canonical categories this rate applies to; every value is a slug from GET /v1/categories. A rate can cover several (e.g. gas and groceries under one cap)."},"merchant":{"type":"string","nullable":true,"description":"Merchant or co-brand partner the rate is limited to (e.g. \"Best Buy\", \"United Airlines\"). Null when it applies anywhere in the category."},"booking_channel":{"type":"string","nullable":true,"enum":["issuer_portal","direct",null],"description":"issuer_portal: only when booked through the issuer's travel portal (Chase Travel, Capital One Travel, ...). direct: booked directly with the airline or hotel."},"choice_group":{"type":"string","nullable":true,"description":"Rates on one card that share a choice_group are alternatives (pick-your-category cards): only choice_picks of them earn at once."},"choice_picks":{"type":"integer","nullable":true,"description":"How many categories in the choice_group earn the rate at the same time."},"choice_selection":{"type":"string","nullable":true,"enum":["user","automatic",null],"description":"user: the cardholder picks; automatic: applied to the top spend categories."},"rate_multiplier":{"type":"number"},"rate_type":{"type":"string","enum":["multiplier","percent_cashback","points_per_dollar"]},"cap_amount":{"type":"number","nullable":true},"cap_period":{"type":"string","nullable":true,"enum":["monthly","quarterly","annual",null]},"fallback_rate":{"type":"number","nullable":true},"is_base_rate":{"type":"boolean"},"is_rotating":{"type":"boolean","description":"True for a quarterly rotating bonus row; see rotating_quarter/rotating_year."},"rotating_quarter":{"type":"integer","nullable":true},"rotating_year":{"type":"integer","nullable":true},"notes":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"CategoryRate":{"type":"object","description":"The rate a card earns in the requested category (GET /v1/cards/best).","properties":{"category_slug":{"type":"string","nullable":true,"description":"The rate's label, as on the card's reward_rates. Label for the rate, unique on its card within a rotating quarter and built from the fields beside it, so the same rate has the same label on every card: <categories>[:<merchant>][@portal|@direct][#choice][~<tag>]. categories: the rate's `categories` joined by \"+\" in /v1/categories order (\"groceries+gas\"); a base rate is \"other\". :<merchant>: the merchant it is limited to, slugged (\"airlines:united-airlines\", \"other:best-buy\"). @portal / @direct: booking_channel issuer_portal / direct (\"travel@portal\"). #choice: one of a pick-your-category group (\"dining#choice\"). ~<tag>: only when two rates of one card would otherwise share a label, e.g. \"airlines:united-airlines~3x\"; a tag can change when the card's other rates change. Match on `categories`, `merchant`, `booking_channel` and `choice_group`, not by parsing the label."},"rate_multiplier":{"type":"number"},"rate_type":{"type":"string","enum":["multiplier","percent_cashback","points_per_dollar"]},"cap_amount":{"type":"number","nullable":true},"cap_period":{"type":"string","nullable":true,"enum":["monthly","quarterly","annual",null]},"categories":{"type":"array","items":{"type":"string"}},"merchant":{"type":"string","nullable":true},"booking_channel":{"type":"string","nullable":true,"enum":["issuer_portal","direct",null]},"choice_group":{"type":"string","nullable":true},"choice_picks":{"type":"integer","nullable":true},"choice_selection":{"type":"string","nullable":true,"enum":["user","automatic",null]},"is_rotating":{"type":"boolean"},"rotating_quarter":{"type":"integer","nullable":true},"rotating_year":{"type":"integer","nullable":true},"notes":{"type":"string","nullable":true}}},"Benefit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"card_id":{"type":"string","format":"uuid"},"benefit_type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"value":{"type":"number","nullable":true},"details":{"type":"object","nullable":true,"description":"Structured coverage detail extracted from the issuer's terms & conditions (when available), e.g. coverage_amount, deductible, covered_reasons, minimum_delay_hours, covers_meals, covers_lodging, max_claims_per_year, is_primary, source."},"created_at":{"type":"string","format":"date-time"}}},"StatementCredit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"card_id":{"type":"string","format":"uuid"},"credit_name":{"type":"string"},"credit_amount":{"type":"number"},"credit_period":{"type":"string","description":"How often the credit renews, e.g. annual, monthly, quarterly, semi_annual."},"eligible_merchants":{"type":"string","nullable":true},"enrollment_required":{"type":"boolean","nullable":true},"notes":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true}}},"CardPerk":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"card_id":{"type":"string","format":"uuid"},"perk_type":{"type":"string"},"perk_name":{"type":"string"},"perk_value":{"type":"number","nullable":true},"perk_period":{"type":"string","nullable":true},"partner":{"type":"string","nullable":true},"details":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true}}},"SpendBonus":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"card_id":{"type":"string","format":"uuid"},"spend_threshold":{"type":"number"},"spend_period":{"type":"string"},"bonus_description":{"type":"string"},"bonus_type":{"type":"string","nullable":true},"bonus_value":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true}}},"Card":{"type":"object","description":"A published card. Which fields are present depends on your plan (see the description of each field group); fields above your plan are left out. GET /v1/cards/search returns no relation arrays.","properties":{"slug":{"type":"string"},"name":{"type":"string"},"issuer_id":{"type":"string","format":"uuid"},"issuers":{"$ref":"#/components/schemas/CardIssuer"},"network":{"type":"string","nullable":true,"enum":["VISA","MC","AMEX","DISCOVER",null]},"card_type":{"type":"string","nullable":true,"enum":["personal","business","student","secured",null]},"annual_fee":{"type":"number","nullable":true,"description":"Annual fee in the card's home currency; null when unknown (not the same as 0)."},"annual_fee_waived_first_year":{"type":"boolean","nullable":true},"reward_currency":{"type":"string","nullable":true,"description":"Broad currency: points, miles or cashback. \"none\" for a card that earns no rewards (low-rate, secured and store-financing cards); such a card has no reward_rates."},"reward_currency_name":{"type":"string","nullable":true,"description":"Program name, e.g. Membership Rewards."},"signup_bonus":{"type":"string","nullable":true,"description":"Welcome offer as stated by the issuer."},"signup_bonus_value":{"type":"number","nullable":true,"deprecated":true,"description":"Legacy: older rows hold a point count for some cards. Since 2026-09-30 a new extraction that states the offer's dollar value (or that there is no offer) rewrites it to the cash value, so it becomes null for points-only offers; an extraction that gives only the offer text leaves it as stored. Use signup_bonus_points and signup_bonus_cash_value."},"signup_bonus_points":{"type":"number","nullable":true,"description":"Points or miles in the welcome offer; null for cash offers and when the offer pays no bonus (e.g. an intro-APR-only offer)."},"signup_bonus_cash_value":{"type":"number","nullable":true,"description":"Estimated welcome offer value in the card's home currency (USD for US cards, CAD for Canadian cards). Never a point count. Null when unknown and when the offer pays no cash, points or miles (e.g. an intro-APR-only offer)."},"signup_min_spend":{"type":"number","nullable":true},"signup_min_spend_months":{"type":"integer","nullable":true},"is_discontinued":{"type":"boolean","nullable":true,"description":"No longer open to new applicants."},"referral_bonus_amount":{"type":"string","nullable":true},"referral_bonus_url":{"type":"string","nullable":true},"product_change_eligible":{"type":"boolean","nullable":true},"product_change_notes":{"type":"string","nullable":true},"product_family":{"type":"string","nullable":true},"churning_notes":{"type":"string","nullable":true},"application_rules":{"type":"string","nullable":true,"description":"Card-level application restrictions."},"reward_rates":{"type":"array","items":{"$ref":"#/components/schemas/RewardRate"},"description":"Free plan: the card's 3 highest rates, best first. Starter and above: every rate."},"id":{"type":"string","format":"uuid"},"monthly_fee":{"type":"number","nullable":true,"description":"Starter plan and above."},"supplementary_card_fee":{"type":"number","nullable":true,"description":"Starter plan and above."},"interest_rate_purchase":{"type":"number","nullable":true,"description":"Starter plan and above."},"interest_rate_cash":{"type":"number","nullable":true,"description":"Starter plan and above."},"interest_rate_balance_transfer":{"type":"number","nullable":true,"description":"Starter plan and above."},"foreign_transaction_fee":{"type":"number","nullable":true,"description":"Starter plan and above."},"credit_score_min":{"type":"integer","nullable":true,"description":"Starter plan and above."},"credit_score_recommended":{"type":"string","nullable":true,"description":"Issuer's credit guidance, e.g. \"Excellent\" or \"670-850\". Starter plan and above."},"min_income":{"type":"number","nullable":true,"description":"Starter plan and above."},"min_income_household":{"type":"number","nullable":true,"description":"Starter plan and above."},"residency_requirement":{"type":"string","nullable":true,"description":"Starter plan and above."},"age_min":{"type":"integer","nullable":true,"description":"Starter plan and above."},"color_from":{"type":"string","nullable":true,"description":"Starter plan and above."},"color_to":{"type":"string","nullable":true,"description":"Starter plan and above."},"color_accent":{"type":"string","nullable":true,"description":"Starter plan and above."},"product_url":{"type":"string","nullable":true,"description":"Starter plan and above."},"apply_url":{"type":"string","nullable":true,"description":"Starter plan and above."},"is_active":{"type":"boolean","description":"Starter plan and above."},"is_published":{"type":"boolean","description":"Starter plan and above."},"source_url":{"type":"string","nullable":true,"description":"Starter plan and above."},"tc_url":{"type":"string","nullable":true,"description":"Terms & conditions page or PDF. Starter plan and above."},"last_scraped":{"type":"string","format":"date-time","nullable":true},"last_verified":{"type":"string","format":"date-time","nullable":true},"last_published":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"intro_apr_purchase":{"type":"number","nullable":true,"description":"Starter plan and above."},"intro_apr_purchase_months":{"type":"integer","nullable":true,"description":"Starter plan and above."},"intro_apr_balance_transfer":{"type":"number","nullable":true,"description":"Starter plan and above."},"intro_apr_balance_transfer_months":{"type":"integer","nullable":true,"description":"Starter plan and above."},"balance_transfer_fee_percent":{"type":"number","nullable":true,"description":"Starter plan and above."},"balance_transfer_fee_min":{"type":"number","nullable":true,"description":"Starter plan and above."},"balance_transfer_fee_intro_percent":{"type":"number","nullable":true,"description":"Starter plan and above."},"balance_transfer_fee_intro_months":{"type":"integer","nullable":true,"description":"Starter plan and above."},"late_payment_fee":{"type":"number","nullable":true,"description":"Starter plan and above."},"returned_payment_fee":{"type":"number","nullable":true,"description":"Starter plan and above."},"cash_advance_fee_percent":{"type":"number","nullable":true,"description":"Starter plan and above."},"cash_advance_fee_min":{"type":"number","nullable":true,"description":"Starter plan and above."},"over_limit_fee":{"type":"number","nullable":true,"description":"Starter plan and above."},"penalty_apr":{"type":"number","nullable":true,"description":"Starter plan and above."},"penalty_apr_trigger":{"type":"string","nullable":true,"description":"Starter plan and above."},"annual_fee_year2":{"type":"number","nullable":true,"description":"Starter plan and above."},"pre_qualification_available":{"type":"boolean","nullable":true,"description":"Starter plan and above."},"pre_qualification_url":{"type":"string","nullable":true,"description":"Starter plan and above."},"hard_pull_bureau":{"type":"string","nullable":true,"description":"Starter plan and above."},"network_tier":{"type":"string","nullable":true,"description":"Starter plan and above."},"authorized_user_fee":{"type":"number","nullable":true,"description":"Starter plan and above."},"authorized_user_earns_rewards":{"type":"boolean","nullable":true,"description":"Starter plan and above."},"authorized_user_max":{"type":"integer","nullable":true,"description":"Starter plan and above."},"authorized_user_min_age":{"type":"integer","nullable":true,"description":"Starter plan and above."},"card_material":{"type":"string","nullable":true,"description":"Starter plan and above."},"card_weight_grams":{"type":"number","nullable":true,"description":"Starter plan and above."},"contactless_enabled":{"type":"boolean","nullable":true,"description":"Starter plan and above."},"chip_and_pin":{"type":"boolean","nullable":true,"description":"Starter plan and above."},"card_color":{"type":"string","nullable":true,"description":"Starter plan and above."},"vertical_design":{"type":"boolean","nullable":true,"description":"Starter plan and above."},"has_rotating_categories":{"type":"boolean","nullable":true,"description":"Starter plan and above."},"rotating_category_activation_required":{"type":"boolean","nullable":true,"description":"Starter plan and above."},"rotating_category_schedule":{"type":"object","nullable":true,"description":"Rotating categories by quarter, e.g. {\"Q1\": [\"groceries\"]}. Starter plan and above."},"annual_reward_cap":{"type":"number","nullable":true,"description":"Starter plan and above."},"annual_reward_cap_notes":{"type":"string","nullable":true,"description":"Starter plan and above."},"benefits":{"type":"array","items":{"$ref":"#/components/schemas/Benefit"},"description":"Starter plan and above."},"statement_credits":{"type":"array","items":{"$ref":"#/components/schemas/StatementCredit"},"description":"Starter plan and above."},"card_perks":{"type":"array","items":{"$ref":"#/components/schemas/CardPerk"},"description":"Starter plan and above."},"historical_best_offer":{"type":"string","nullable":true,"description":"Pro plan and above."},"historical_best_offer_date":{"type":"string","format":"date","nullable":true,"description":"Pro plan and above."},"spend_bonuses":{"type":"array","items":{"$ref":"#/components/schemas/SpendBonus"},"description":"Pro plan and above."},"military_annual_fee_waived":{"type":"boolean","nullable":true,"description":"Pro plan and above."},"military_apr_cap":{"type":"number","nullable":true,"description":"Pro plan and above."},"military_benefits_notes":{"type":"string","nullable":true,"description":"Pro plan and above."},"image_url":{"type":"string","nullable":true,"description":"Card art. Enterprise plan only."},"affiliate_url":{"type":"string","nullable":true,"description":"Enterprise plan only."}}},"RankedCard":{"allOf":[{"$ref":"#/components/schemas/Card"},{"type":"object","properties":{"category_rate":{"$ref":"#/components/schemas/CategoryRate"}}}]},"CardSummary":{"allOf":[{"$ref":"#/components/schemas/Card"}],"deprecated":true,"description":"Deprecated: use Card."},"CardDetail":{"allOf":[{"$ref":"#/components/schemas/Card"}],"deprecated":true,"description":"Deprecated: use Card."},"Issuer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"country":{"type":"string","enum":["US","CA"]},"logo_url":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"cards_url":{"type":"string","nullable":true},"is_active":{"type":"boolean"},"card_count":{"type":"integer","description":"Published cards from this issuer."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Category":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"icon":{"type":"string","nullable":true},"sort_order":{"type":"integer"},"parent_slug":{"type":"string","nullable":true,"description":"Broader category this one belongs to, e.g. airlines -> travel."}}},"CardChange":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"card_id":{"type":"string","format":"uuid"},"changed_fields":{"type":"object","description":"Field name -> its old and new value (either may be null). Only fields whose value changed, and only fields your plan includes.","additionalProperties":{"type":"object","properties":{"old":{},"new":{}}}},"snapshot":{"type":"object","nullable":true,"description":"The card before the change, with the fields your plan includes."},"changed_at":{"type":"string","format":"date-time","nullable":true}}},"TransferPartner":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"source_currency":{"type":"string","description":"Program code, e.g. MR, UR, TYP, C1."},"partner_program":{"type":"string"},"partner_type":{"type":"string","nullable":true,"description":"airline or hotel"},"transfer_ratio_from":{"type":"integer"},"transfer_ratio_to":{"type":"integer"},"country":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"is_active":{"type":"boolean","nullable":true},"transfer_minimum":{"type":"integer","nullable":true},"transfer_time":{"type":"string","nullable":true},"transfer_bonus_current":{"type":"string","nullable":true},"transfer_bonus_expires":{"type":"string","nullable":true}}},"ApplicationRule":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"issuer_id":{"type":"string","format":"uuid","nullable":true},"rule_name":{"type":"string"},"rule_type":{"type":"string","nullable":true},"description":{"type":"string"},"details":{"type":"object","nullable":true,"description":"Rule parameters, e.g. max_cards and period_months."},"country":{"type":"string","nullable":true},"is_active":{"type":"boolean","nullable":true},"issuers":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}}}}},"OfferChange":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"card_id":{"type":"string","format":"uuid"},"field_name":{"type":"string"},"old_value":{"type":"string","nullable":true},"new_value":{"type":"string","nullable":true},"change_type":{"type":"string","nullable":true,"enum":["increased","decreased","added","removed","changed",null]},"is_notable":{"type":"boolean","nullable":true},"detected_at":{"type":"string","format":"date-time","nullable":true}}},"NotableOfferChange":{"allOf":[{"$ref":"#/components/schemas/OfferChange"},{"type":"object","properties":{"card_slug":{"type":"string"},"card_name":{"type":"string"},"card_image_url":{"type":"string","nullable":true,"description":"Card art. Enterprise plan only."},"card_affiliate_url":{"type":"string","nullable":true,"description":"Enterprise plan only."}}}]},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["card.created","card.updated","card.deleted","offer.notable"]}},"is_active":{"type":"boolean","nullable":true},"last_triggered_at":{"type":"string","format":"date-time","nullable":true},"failure_count":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true}}},"WebhookWithSecret":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string","description":"HMAC signing secret (shown only on creation)"}}}]},"RewardValuation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"currency_name":{"type":"string"},"currency_code":{"type":"string"},"cpp_cash":{"type":"number"},"cpp_travel_portal":{"type":"number","nullable":true},"cpp_transfer":{"type":"number","nullable":true},"cpp_recommended":{"type":"number"},"last_updated":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true}}},"ProductChangeCard":{"type":"object","nullable":true,"properties":{"slug":{"type":"string"},"name":{"type":"string"},"issuers":{"type":"object","nullable":true,"properties":{"slug":{"type":"string"},"name":{"type":"string"}}}}},"ProductChangePath":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"from_card_id":{"type":"string","format":"uuid"},"to_card_id":{"type":"string","format":"uuid"},"direction":{"type":"string","description":"upgrade, downgrade, both (either way) or one_way (from_card to to_card only, as recorded from an issuer page)"},"notes":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true},"from_card":{"$ref":"#/components/schemas/ProductChangeCard"},"to_card":{"$ref":"#/components/schemas/ProductChangeCard"}}},"Usage":{"type":"object","description":"Usage counts cover every key on the account, including revoked keys.","properties":{"tier":{"type":"string","enum":["free","starter","pro","enterprise"]},"daily_used":{"type":"integer"},"daily_limit":{"type":"integer"},"monthly_used":{"type":"integer"},"monthly_limit":{"type":"integer"}},"required":["tier","daily_used","daily_limit","monthly_used","monthly_limit"]},"Stats":{"type":"object","properties":{"total_cards":{"type":"integer"},"published_cards":{"type":"integer"},"total_issuers":{"type":"integer"},"issuers_by_country":{"type":"object","additionalProperties":{"type":"integer"}},"last_updated":{"type":"string","format":"date-time","nullable":true}}}},"parameters":{"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"default":20},"description":"Results per page, 1 or more (default 20; values above 100 are treated as 100). Not an integer: 400."},"Offset":{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Results to skip. An offset past the last result returns an empty page."}}},"paths":{"/v1/cards":{"get":{"summary":"List credit cards","description":"Published cards, sorted by name, with optional filters. Discontinued cards are left out unless include_discontinued=true. An offset past the end returns an empty page.","tags":["Cards"],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"name":"country","in":"query","schema":{"type":"string","enum":["US","CA"]},"description":"Filter by issuer country"},{"name":"issuer","in":"query","schema":{"type":"string"},"description":"Filter by issuer slug"},{"name":"network","in":"query","schema":{"type":"string","enum":["VISA","MC","AMEX","DISCOVER"]},"description":"Filter by card network (case-insensitive)"},{"name":"type","in":"query","schema":{"type":"string","enum":["personal","business","student","secured"]},"description":"Filter by card type"},{"name":"max_annual_fee","in":"query","schema":{"type":"number","minimum":0},"description":"Maximum annual fee. Not a number: 400."},{"name":"no_annual_fee","in":"query","schema":{"type":"boolean"},"description":"Only cards with a stated $0 annual fee"},{"name":"credit_score","in":"query","schema":{"type":"integer","minimum":0},"description":"Only cards whose minimum credit score is at or below this (or not stated). Not an integer: 400."},{"name":"include_discontinued","in":"query","schema":{"type":"boolean","default":false},"description":"Also list cards no longer open to new applicants."}],"responses":{"200":{"description":"Paginated list of cards","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Card"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["data","total","limit","offset"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/cards/{slug}":{"get":{"summary":"Get card details","description":"Full details for one card. Which fields are present depends on your plan.","tags":["Cards"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,99}$"},"description":"Card slug"}],"responses":{"200":{"description":"Card details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Card"}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/cards/search":{"get":{"summary":"Search cards","description":"Searches card names and issuer names; exact and prefix name matches rank first. '*' is ignored (not a wildcard). Results carry no relation arrays (reward_rates, benefits and so on); fetch a card for those.","tags":["Cards"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":200},"description":"Search text"},{"name":"country","in":"query","schema":{"type":"string","enum":["US","CA"]},"description":"Only return cards from issuers in this country"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Card"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["data","total","limit","offset"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/cards/compare":{"get":{"summary":"Compare cards","description":"2-5 cards side by side, in the order requested. An unknown slug is a 404 that names it.","tags":["Cards"],"parameters":[{"name":"slugs","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated card slugs (2-5 different cards)"}],"responses":{"200":{"description":"The cards, in the order requested","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Card"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/cards/best":{"get":{"summary":"Get best cards for a category","description":"Returns cards ranked by reward rate for a spending category, one entry per card with the matching rate in `category_rate` (every plan gets it). Only the active quarter's rotating rows count. Merchant-only, portal-only and pick-your-category rates are left out unless include_restricted=true, and are flagged in `category_rate` when included.","tags":["Cards"],"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string"},"description":"Spending category slug from GET /v1/categories (common aliases such as `drugstores` or `restaurants` are accepted, and so is a reward rate's `category_slug` label that names one category: `dining#choice` and `travel@portal` ask for dining and travel). Matches each rate's canonical `categories`."},{"name":"include_restricted","in":"query","schema":{"type":"boolean","default":false},"description":"Also rank restricted rates: limited to one merchant, only through the issuer's travel portal (e.g. 5% on Chase Travel), or one of several pick-your-category options (e.g. Citi Custom Cash). Off by default."},{"name":"country","in":"query","schema":{"type":"string","enum":["US","CA"]}},{"name":"max_annual_fee","in":"query","schema":{"type":"number","minimum":0},"description":"Not a number: 400."},{"name":"no_annual_fee","in":"query","schema":{"type":"boolean"},"description":"Only cards with a stated $0 annual fee (an unknown fee does not count as free)."},{"name":"include_discontinued","in":"query","schema":{"type":"boolean","default":false},"description":"Also rank cards no longer open to new applicants. Off by default, as on GET /v1/cards."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"default":10},"description":"1 or more (default 10; values above 50 are treated as 50)."}],"responses":{"200":{"description":"Ranked cards","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RankedCard"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/issuers":{"get":{"summary":"List issuers","description":"Card issuers, optionally filtered by country, with their number of published cards.","tags":["Issuers"],"parameters":[{"name":"country","in":"query","schema":{"type":"string","enum":["US","CA"]},"description":"Filter by country"}],"responses":{"200":{"description":"List of issuers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Issuer"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/issuers/{slug}":{"get":{"summary":"Get issuer details","description":"Details for a single issuer, with its number of published cards.","tags":["Issuers"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,99}$"},"description":"Issuer slug"}],"responses":{"200":{"description":"Issuer details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Issuer"}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/categories":{"get":{"summary":"List spending categories","description":"Returns all spending categories. Every reward rate's `categories` values come from this list, and its `category_slug` label starts with them, joined by \"+\" in this list's order.","tags":["Meta"],"responses":{"200":{"description":"List of categories","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/stats":{"get":{"summary":"Get database statistics","description":"Aggregate counts and when card data last changed. No API key needed.","tags":["Meta"],"security":[],"responses":{"200":{"description":"Database statistics","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Stats"}},"required":["data"]}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/auth/register":{"post":{"summary":"Start sign-up","description":"Emails a sign-in link to the address. Opening it confirms the email and signs the owner in to the developer portal at cardapi.dev/portal, where the free API key is created; no key is returned here. The response is the same whether or not the address already has an account. No API key needed. Rate limited by IP (5 an hour, 10 a day); malformed requests don't count.","tags":["Auth"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"]}}}},"responses":{"202":{"description":"Sign-in link sent (if the address can receive one)","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["verification_pending"]},"message":{"type":"string"},"portal_url":{"type":"string","format":"uri"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"description":"Too many sign-up attempts from this IP, or a link was sent to this address in the last minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/auth/keys":{"post":{"summary":"Generate additional API key","description":"Creates a new API key for your account, on your account's plan; it shares the account's quota. The key is returned once and cannot be retrieved again. At most 5 active keys per account.","tags":["Auth"],"responses":{"201":{"description":"New API key created","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string","description":"Shown once"}}}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/auth/usage":{"get":{"summary":"Check usage and limits","description":"Your plan, and your account's usage today and this month against its limits. Quotas are per account, so the counts cover every key on the account, including revoked keys.","tags":["Auth"],"responses":{"200":{"description":"Usage and limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/auth/upgrade":{"post":{"summary":"Start a paid plan","description":"Starts a paid plan for an account that doesn't have one: returns a Stripe Checkout URL where the cardholder completes payment (Starter starts with a 7-day free trial, once per customer). An API key never changes an existing paid plan, because that would bill the saved card: when the account already has one the answer is 409 use_portal, and the plan is changed, cancelled or its card updated in the developer portal at https://cardapi.dev/portal, signed in as the account owner (or email support@cardapi.dev).","tags":["Auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","enum":["starter","pro","enterprise"]},"billing":{"type":"string","enum":["monthly","annual"],"default":"monthly"}},"required":["tier"]}}}},"responses":{"200":{"description":"A Stripe Checkout URL for the cardholder to complete; the plan starts once it is paid (updated is always false)","content":{"application/json":{"schema":{"type":"object","properties":{"checkout_url":{"type":"string"},"updated":{"type":"boolean","enum":[false]},"trial":{"type":"boolean","description":"True when Starter starts with the 7-day free trial"}},"required":["checkout_url","updated","trial"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"payment_required: the account's last payment failed; update the card in the developer portal first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"use_portal: the account already has a paid plan, which is changed in the developer portal, not with an API key. Also already_on_plan, or plan_cancelling when the plan is set to cancel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/cards/{slug}/history":{"get":{"summary":"Get card change history","description":"Tracked changes to one card, newest first: the changed fields (old and new values) and the card before the change. Pro plan and above.","tags":["Cards"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,99}$"},"description":"Card slug"}],"responses":{"200":{"description":"Card change history","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CardChange"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/cards/{slug}/transfers":{"get":{"summary":"Get card transfer partners","description":"Loyalty programs the card's points transfer to. An empty list means the card's program has no known partners. Pro plan and above.","tags":["Cards"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,99}$"},"description":"Card slug"}],"responses":{"200":{"description":"Transfer partners for this card","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TransferPartner"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/transfer-partners":{"get":{"summary":"List transfer partners","description":"The directory of loyalty program transfer partners, optionally for one program. Pro plan and above.","tags":["Transfer Partners"],"parameters":[{"name":"currency","in":"query","schema":{"type":"string"},"description":"Program code, e.g. MR, UR, TYP, C1"}],"responses":{"200":{"description":"List of transfer partners","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TransferPartner"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/application-rules":{"get":{"summary":"List application rules","description":"Issuer application rules (e.g. Chase 5/24, Amex once-per-lifetime), optionally for one issuer.","tags":["Application Rules"],"parameters":[{"name":"issuer","in":"query","schema":{"type":"string"},"description":"Filter by issuer slug"}],"responses":{"200":{"description":"List of application rules","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApplicationRule"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/issuers/{slug}/rules":{"get":{"summary":"Get issuer-specific application rules","description":"Application rules for one issuer. An unknown issuer is a 404; an issuer with no rules gives an empty list.","tags":["Issuers"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,99}$"},"description":"Issuer slug"}],"responses":{"200":{"description":"Application rules for this issuer","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApplicationRule"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/offers/notable":{"get":{"summary":"Get notable offer changes","description":"Recent notable changes to signup bonuses, annual fees and other offers on published cards. Pro plan and above.","tags":["Offers"],"parameters":[{"name":"country","in":"query","schema":{"type":"string","enum":["US","CA"]},"description":"Filter by issuer country"}],"responses":{"200":{"description":"List of notable offer changes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotableOfferChange"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/offers/history":{"get":{"summary":"Get offer history for a card","description":"Offer changes for one card, newest first. An unknown card is a 404. Pro plan and above.","tags":["Offers"],"parameters":[{"name":"card_slug","in":"query","required":true,"schema":{"type":"string"},"description":"Card slug"}],"responses":{"200":{"description":"Offer change history","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OfferChange"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/webhooks":{"post":{"summary":"Create webhook","description":"Registers an HTTPS endpoint to receive event notifications. Returns a signing secret that is shown only once; each delivery carries X-CardAPI-Signature: sha256=<HMAC-SHA256 of the body with that secret>. At most 20 per key. card.updated: a published card's data changed, from a scrape or an edit by CardAPI, and is sent only when something did change (data: id, slug, name, the fields written, changes with each changed field's old and new value, and changed_relations naming the related tables that changed, such as reward_rates). card.created: a card joined the catalog (data.reason: published for a newly published card, reinstated when a discontinued card came back). card.deleted: a card left the catalog (data.reason: discontinued, when GET /v1/cards no longer lists it by default but its slug still resolves; or unpublished, when CardAPI withdrew it and its slug no longer resolves). offer.notable: a welcome offer went up, its minimum spend or the annual fee came down, or a first-year fee waiver was added. Enterprise plan only.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"HTTPS URL to receive webhook payloads"},"events":{"type":"array","items":{"type":"string","enum":["card.created","card.updated","card.deleted","offer.notable"]},"description":"Event types to subscribe to"}},"required":["url","events"]}}}},"responses":{"201":{"description":"Webhook created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookWithSecret"}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"get":{"summary":"List webhooks","description":"Webhook endpoints registered for the API key making the request. Enterprise plan only.","tags":["Webhooks"],"responses":{"200":{"description":"List of webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/webhooks/{id}":{"delete":{"summary":"Delete webhook","description":"Removes a webhook endpoint. Enterprise plan only.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook ID"}],"responses":{"200":{"description":"Webhook deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/reward-valuations":{"get":{"summary":"List reward currency valuations","description":"Valuations for every reward currency: cents-per-point estimates for cash, travel portal and transfer partner redemptions.","tags":["Meta"],"responses":{"200":{"description":"List of reward valuations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RewardValuation"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/product-changes":{"get":{"summary":"List product change paths","description":"Product change (upgrade/downgrade) paths between cards, optionally for one issuer. Coverage is limited: a path is recorded only when the issuer's own page names the card it can switch to.","tags":["Cards"],"parameters":[{"name":"issuer","in":"query","schema":{"type":"string"},"description":"Filter by issuer slug"}],"responses":{"200":{"description":"List of product change paths","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductChangePath"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/cards/{slug}/perks":{"get":{"summary":"Get card perks","description":"Companion perks for one card: hotel and rental-car status, lounge access and similar. Starter plan and above.","tags":["Cards"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,99}$"},"description":"Card slug"}],"responses":{"200":{"description":"Card perks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CardPerk"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/cards/{slug}/credits":{"get":{"summary":"Get card statement credits","description":"Statement credits for one card (dining, Uber, airline fee, streaming and so on), largest first. Starter plan and above.","tags":["Cards"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,99}$"},"description":"Card slug"}],"responses":{"200":{"description":"Card statement credits","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StatementCredit"}}},"required":["data"]}}},"headers":{"X-CardAPI-Plan":{"$ref":"#/components/headers/X-CardAPI-Plan"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/health":{"get":{"summary":"Health check","tags":["System"],"security":[],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"commit":{"type":"string","description":"Deployed commit SHA, or \"unknown\" if not set"},"started_at":{"type":"string","format":"date-time"}}}}}}}}}}}