{"openapi":"3.0.3","info":{"title":"CardAPI","version":"1.0.0","description":"Comprehensive credit card data API for US and Canada. Provides detailed card information including reward rates, benefits, fees, and signup bonuses."},"servers":[{"url":"https://api.cardapi.dev","description":"Production"},{"url":"http://localhost:3100","description":"Local"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key with 'Bearer ' prefix, e.g. 'Bearer ck_live_...'"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"RewardRate":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"card_id":{"type":"string","format":"uuid"},"category_slug":{"type":"string","nullable":true},"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","enum":["monthly","quarterly","annual"],"nullable":true},"fallback_rate":{"type":"number","nullable":true},"is_base_rate":{"type":"boolean"},"is_rotating":{"type":"boolean"},"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}}},"CardSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"network":{"type":"string","enum":["VISA","MC","AMEX","DISCOVER"],"nullable":true},"card_type":{"type":"string","enum":["personal","business","student","secured"],"nullable":true},"annual_fee":{"type":"number","nullable":true},"annual_fee_waived_first_year":{"type":"boolean","nullable":true},"reward_currency":{"type":"string","nullable":true},"signup_bonus":{"type":"string","nullable":true},"signup_bonus_value":{"type":"number","nullable":true},"image_url":{"type":"string","nullable":true},"product_url":{"type":"string","nullable":true},"issuer":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"country":{"type":"string","enum":["US","CA"]},"logo_url":{"type":"string","nullable":true}}}}},"CardDetail":{"allOf":[{"$ref":"#/components/schemas/CardSummary"},{"type":"object","properties":{"monthly_fee":{"type":"number","nullable":true},"supplementary_card_fee":{"type":"number","nullable":true},"interest_rate_purchase":{"type":"number","nullable":true},"interest_rate_cash":{"type":"number","nullable":true},"interest_rate_balance_transfer":{"type":"number","nullable":true},"foreign_transaction_fee":{"type":"number","nullable":true},"signup_min_spend":{"type":"number","nullable":true},"signup_min_spend_months":{"type":"number","nullable":true},"reward_currency_name":{"type":"string","nullable":true},"credit_score_min":{"type":"number","nullable":true},"min_income":{"type":"number","nullable":true},"apply_url":{"type":"string","nullable":true},"reward_rates":{"type":"array","items":{"$ref":"#/components/schemas/RewardRate"}},"benefits":{"type":"array","items":{"$ref":"#/components/schemas/Benefit"}}}}]},"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}}},"Category":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"icon":{"type":"string","nullable":true},"sort_order":{"type":"number"}}},"CardChange":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"card_id":{"type":"string","format":"uuid"},"field":{"type":"string"},"old_value":{"type":"string","nullable":true},"new_value":{"type":"string","nullable":true},"detected_at":{"type":"string","format":"date-time"}}},"TransferPartner":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"program_name":{"type":"string","nullable":true},"currency":{"type":"string"},"transfer_ratio":{"type":"number","nullable":true},"transfer_time":{"type":"string","nullable":true},"partner_type":{"type":"string","nullable":true}}},"ApplicationRule":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"issuer_slug":{"type":"string"},"rule_name":{"type":"string"},"description":{"type":"string","nullable":true},"rule_type":{"type":"string","nullable":true},"details":{"type":"object","nullable":true}}},"OfferChange":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"card_slug":{"type":"string"},"card_name":{"type":"string","nullable":true},"change_type":{"type":"string"},"old_value":{"type":"string","nullable":true},"new_value":{"type":"string","nullable":true},"detected_at":{"type":"string","format":"date-time"},"is_notable":{"type":"boolean"}}},"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"},"last_triggered_at":{"type":"string","format":"date-time","nullable":true},"failure_count":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"WebhookWithSecret":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string","description":"HMAC signing secret (shown only on creation)"}}}]},"PaginatedResponse":{"type":"object","properties":{"data":{"type":"array","items":{}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}},"parameters":{"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of results to return"},"Offset":{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Number of results to skip"}}},"paths":{"/v1/cards":{"get":{"summary":"List credit cards","description":"Returns a paginated list of published credit cards with optional filters.","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"},"description":"Maximum annual fee"},{"name":"no_annual_fee","in":"query","schema":{"type":"boolean"},"description":"Only cards with no annual fee"},{"name":"credit_score","in":"query","schema":{"type":"integer"},"description":"Filter by minimum credit score"}],"responses":{"200":{"description":"Paginated list of cards","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CardSummary"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cards/{slug}":{"get":{"summary":"Get card details","description":"Returns full details for a single card including reward rates and benefits.","tags":["Cards"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Card slug identifier"}],"responses":{"200":{"description":"Card details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CardDetail"}}}}}},"404":{"description":"Card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cards/search":{"get":{"summary":"Search cards","description":"Full-text search across card names and issuer names.","tags":["Cards"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query"},{"$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/CardSummary"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"400":{"description":"Missing query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cards/compare":{"get":{"summary":"Compare cards","description":"Compare 2-5 cards side by side.","tags":["Cards"],"parameters":[{"name":"slugs","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated card slugs (2-5)"}],"responses":{"200":{"description":"Comparison results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CardDetail"}}}}}}},"400":{"description":"Invalid slugs parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cards/best":{"get":{"summary":"Get best cards for a category","description":"Returns cards ranked by reward rate for a spending category.","tags":["Cards"],"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string"},"description":"Spending category slug"},{"name":"country","in":"query","schema":{"type":"string","enum":["US","CA"]}},{"name":"max_annual_fee","in":"query","schema":{"type":"number"}},{"name":"no_annual_fee","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"Ranked cards","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Missing category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/issuers":{"get":{"summary":"List issuers","description":"Returns all card issuers, optionally filtered by country.","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"}}}}}}}}}},"/v1/issuers/{slug}":{"get":{"summary":"Get issuer details","description":"Returns details for a single issuer.","tags":["Issuers"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Issuer slug identifier"}],"responses":{"200":{"description":"Issuer details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Issuer"}}}}}},"404":{"description":"Issuer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/categories":{"get":{"summary":"List spending categories","description":"Returns all spending categories used for reward rates.","tags":["Meta"],"responses":{"200":{"description":"List of categories","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}}}}},"/v1/stats":{"get":{"summary":"Get database statistics","description":"Returns aggregate counts and metadata about the database.","tags":["Meta"],"responses":{"200":{"description":"Database statistics","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total_cards":{"type":"integer"},"published_cards":{"type":"integer"},"issuers_by_country":{"type":"object"},"last_updated":{"type":"string","format":"date-time"}}}}}}}}}}},"/v1/auth/register":{"post":{"summary":"Register for an API key","description":"Create a new account and receive a free-tier API key.","tags":["Auth"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"}},"required":["email"]}}}},"responses":{"201":{"description":"Registration successful","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string"},"tier":{"type":"string"}}}}}}}}},"/v1/auth/keys":{"post":{"summary":"Generate additional API key","description":"Creates a new API key for your account. The key is returned once and cannot be retrieved again.","tags":["Auth"],"responses":{"201":{"description":"New API key created","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string"},"tier":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/usage":{"get":{"summary":"Check usage and limits","description":"Returns current billing period usage, rate limits, and tier information for the authenticated API key.","tags":["Auth"],"responses":{"200":{"description":"Usage and limit data","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tier":{"type":"string","enum":["free","pro","enterprise"]},"usage":{"type":"integer"},"limit":{"type":"integer"},"period_start":{"type":"string","format":"date-time"},"period_end":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/upgrade":{"post":{"summary":"Upgrade API tier","tags":["Auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","enum":["pro","enterprise"]}},"required":["tier"]}}}},"responses":{"200":{"description":"Upgrade initiated"}}}},"/v1/cards/{slug}/history":{"get":{"summary":"Get card change history","description":"Returns a chronological log of detected changes for a card. Requires a Pro or Enterprise plan.","tags":["Cards"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Card slug identifier"}],"responses":{"200":{"description":"Card change history","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CardChange"}}}}}}},"403":{"description":"Pro or Enterprise plan required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cards/{slug}/transfers":{"get":{"summary":"Get card transfer partners","description":"Returns the transfer partners available for a specific card's reward currency.","tags":["Cards"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Card slug identifier"}],"responses":{"200":{"description":"Transfer partners for this card","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TransferPartner"}}}}}}}}}},"/v1/transfer-partners":{"get":{"summary":"List transfer partners","description":"Returns the full directory of loyalty program transfer partners, optionally filtered by reward currency.","tags":["Transfer Partners"],"parameters":[{"name":"currency","in":"query","schema":{"type":"string"},"description":"Filter by reward currency (e.g. 'MR', 'UR', 'Aeroplan')"}],"responses":{"200":{"description":"List of transfer partners","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TransferPartner"}}}}}}}}}},"/v1/application-rules":{"get":{"summary":"List application rules","description":"Returns issuer application rules (e.g. Chase 5/24, Amex once-per-lifetime). Optionally filter by issuer slug.","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"}}}}}}}}}},"/v1/issuers/{slug}/rules":{"get":{"summary":"Get issuer-specific application rules","description":"Returns application rules for a specific issuer.","tags":["Issuers"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Issuer slug identifier"}],"responses":{"200":{"description":"Application rules for this issuer","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApplicationRule"}}}}}}}}}},"/v1/offers/notable":{"get":{"summary":"Get notable offer changes","description":"Returns recent notable changes to signup bonuses, annual fees, and other card offers. Useful for deal alerts.","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/OfferChange"}}}}}}}}}},"/v1/offers/history":{"get":{"summary":"Get offer history for a card","description":"Returns the full offer change history for a specific card.","tags":["Offers"],"parameters":[{"name":"card_slug","in":"query","required":true,"schema":{"type":"string"},"description":"Card slug to retrieve offer history for"}],"responses":{"200":{"description":"Offer change history","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OfferChange"}}}}}}},"400":{"description":"Missing card_slug parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks":{"post":{"summary":"Create webhook","description":"Registers a webhook endpoint to receive event notifications. Requires an Enterprise plan. Returns a signing secret that is shown only once.","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"}}}}}},"400":{"description":"Invalid URL or events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Enterprise plan required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List webhooks","description":"Returns all webhook endpoints registered for the authenticated API key. Requires an Enterprise plan.","tags":["Webhooks"],"responses":{"200":{"description":"List of webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"403":{"description":"Enterprise plan required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}":{"delete":{"summary":"Delete webhook","description":"Removes a webhook endpoint. Requires an Enterprise plan.","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"}}}}}},"403":{"description":"Enterprise plan required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/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"]}}}}}}}}}}}