{"openapi":"3.1.0","info":{"title":"Card Optimizer public API","summary":"Which credit card earns the most for a purchase.","description":"Read-only, free and without keys. Please credit Card Optimizer and link to the `link` in each answer. Limits: 60 requests a minute per address. Estimates from published earn rates and typical point values, not financial advice. Rates and offers change, so verify with the issuer. Docs: https://cardoptimizer.app/mcp","version":"1.0.0"},"servers":[{"url":"https://cardoptimizer.app/api"}],"paths":{"/v1/best-card":{"get":{"tags":["public"],"summary":"Which card earns the most for a purchase","description":"Ranks the given cards, or the whole catalog, by estimated dollar value.\n\nBonus caps count as unused, since nothing is tracked between calls.","operationId":"best_card","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"description":"A store (\"Costco\", \"whole foods\") or a category (\"groceries\", \"gas\").","examples":["Costco"],"title":"Q"},"description":"A store (\"Costco\", \"whole foods\") or a category (\"groceries\", \"gas\")."},{"name":"amount","in":"query","required":true,"schema":{"anyOf":[{"type":"number","maximum":1000000.0,"exclusiveMinimum":0.0},{"type":"string"}],"description":"Dollars.","examples":["100"],"title":"Amount"},"description":"Dollars."},{"name":"cards","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z0-9_]+(,[a-z0-9_]+){0,49}$"},{"type":"null"}],"description":"The caller's card ids, comma-separated (see /v1/cards). Leave out to rank every card.","examples":["amex_gold,citi_double_cash"],"title":"Cards"},"description":"The caller's card ids, comma-separated (see /v1/cards). Leave out to rank every card."},{"name":"picks","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z0-9_]+\\.[a-z0-9_]+:[a-z0-9_]+(\\.[a-z0-9_]+)*(,[a-z0-9_]+\\.[a-z0-9_]+:[a-z0-9_]+(\\.[a-z0-9_]+)*)*$"},{"type":"null"}],"description":"Picked categories on cards that let you choose, as card.choice:option, comma-separated. A choice left out uses the issuer's default.","examples":["bofa_customized_cash.choice:dining"],"title":"Picks"},"description":"Picked categories on cards that let you choose, as card.choice:option, comma-separated. A choice left out uses the issuer's default."},{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Purchase date, for rotating categories. Defaults to today (UTC).","title":"Date"},"description":"Purchase date, for rotating categories. Defaults to today (UTC)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BestCardOut"}}}},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}},"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Problem details"},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}},"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Problem details"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}},"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Problem details"}}}},"/v1/merchants":{"get":{"tags":["public"],"summary":"Search stores","description":"Stores Card Optimizer knows, best match first, with the category each counts as.","operationId":"search_merchants","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Part of a store's name, typos allowed.","title":"Q"},"description":"Part of a store's name, typos allowed."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":25,"minimum":1,"default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantSearchOut"}}}},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}},"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Problem details"},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}},"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Problem details"}}}},"/v1/cards":{"get":{"tags":["public"],"summary":"List the cards Card Optimizer knows","description":"Every card id, for the `cards` parameter.","operationId":"list_cards","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardListOut"}}}},"429":{"description":"Problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}},"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"schemas":{"BestCardOut":{"properties":{"source":{"$ref":"#/components/schemas/SourceOut"},"link":{"type":"string","title":"Link","description":"This answer on cardoptimizer.app, to link to."},"matched":{"$ref":"#/components/schemas/MatchedOut"},"compared":{"type":"string","enum":["your_cards","catalog"],"title":"Compared","description":"`your_cards` ranks the cards passed in `cards`; `catalog` ranks every card Card Optimizer knows and lists the top 5."},"best":{"anyOf":[{"$ref":"#/components/schemas/ResultOut"},{"type":"null"}],"description":"The card to use, or null if none can be used."},"results":{"items":{"$ref":"#/components/schemas/ResultOut"},"type":"array","title":"Results"},"ineligible":{"items":{"$ref":"#/components/schemas/IneligibleOut"},"type":"array","title":"Ineligible","description":"Cards on a network the store doesn't take. Empty for `catalog`."},"purchase":{"$ref":"#/components/schemas/PurchaseOut"}},"type":"object","required":["source","link","matched","compared","best","results","ineligible","purchase"],"title":"BestCardOut"},"CardListOut":{"properties":{"source":{"$ref":"#/components/schemas/SourceOut"},"cards":{"items":{"$ref":"#/components/schemas/PublicCardOut"},"type":"array","title":"Cards"}},"type":"object","required":["source","cards"],"title":"CardListOut"},"Category":{"type":"string","enum":["dining","groceries","gas","travel","airfare","hotels","transit","streaming","drugstores","online_shopping","wholesale_clubs","home_improvement","entertainment","utilities","cable_and_internet","phone_plans","fast_food","movie_theaters","department_stores","electronics_stores","furniture_stores","clothing_stores","sporting_goods","gyms","other"],"title":"Category"},"FreshnessOut":{"properties":{"source_url":{"type":"string","title":"Source Url"},"verified_against":{"type":"string","enum":["issuer","third_party"],"title":"Verified Against"},"last_verified":{"type":"string","format":"date","title":"Last Verified"},"unverified_fields":{"items":{"type":"string"},"type":"array","title":"Unverified Fields"}},"type":"object","required":["source_url","verified_against","last_verified","unverified_fields"],"title":"FreshnessOut"},"IneligibleOut":{"properties":{"card_id":{"type":"string","title":"Card Id"},"card_name":{"type":"string","title":"Card Name"},"reason":{"type":"string","title":"Reason"}},"type":"object","required":["card_id","card_name","reason"],"title":"IneligibleOut"},"MatchedOut":{"properties":{"kind":{"type":"string","enum":["merchant","category"],"title":"Kind"},"name":{"type":"string","title":"Name","description":"The store's name, or the category as it reads in a sentence."},"category":{"$ref":"#/components/schemas/Category"},"guessed":{"type":"boolean","title":"Guessed","description":"True when the name matched no store and the category was guessed from it, such as dining for \"Joe's Pizza\"."}},"type":"object","required":["kind","name","category","guessed"],"title":"MatchedOut"},"MerchantOut":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"category":{"$ref":"#/components/schemas/Category"},"accepted_networks":{"anyOf":[{"items":{"$ref":"#/components/schemas/Network"},"type":"array"},{"type":"null"}],"title":"Accepted Networks"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","required":["id","name","category","accepted_networks","notes"],"title":"MerchantOut"},"MerchantSearchOut":{"properties":{"source":{"$ref":"#/components/schemas/SourceOut"},"results":{"items":{"$ref":"#/components/schemas/PublicMerchantOut"},"type":"array","title":"Results"}},"type":"object","required":["source","results"],"title":"MerchantSearchOut"},"Network":{"type":"string","enum":["visa","mastercard","amex","discover"],"title":"Network"},"Problem":{"properties":{"type":{"type":"string","title":"Type"},"title":{"type":"string","title":"Title"},"status":{"type":"integer","title":"Status"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"},"errors":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Errors"},"suggestions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Suggestions","description":"For an unknown merchant: known merchants with similar names."},"category":{"anyOf":[{"$ref":"#/components/schemas/Category"},{"type":"null"}],"description":"For an unknown merchant: the category its name suggests, such as dining for \"Joe's Pizza\". Absent when nothing in the name is telling."}},"type":"object","required":["type","title","status"],"title":"Problem"},"PublicCardOut":{"properties":{"id":{"type":"string","title":"Id","description":"Pass this in `cards`."},"name":{"type":"string","title":"Name"},"network":{"$ref":"#/components/schemas/Network"},"annual_fee":{"type":"string","title":"Annual Fee"}},"type":"object","required":["id","name","network","annual_fee"],"title":"PublicCardOut"},"PublicMerchantOut":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"category":{"$ref":"#/components/schemas/Category"},"accepted_networks":{"anyOf":[{"items":{"$ref":"#/components/schemas/Network"},"type":"array"},{"type":"null"}],"title":"Accepted Networks"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"},"link":{"type":"string","title":"Link","description":"The store's best-card page on cardoptimizer.app."}},"type":"object","required":["id","name","category","accepted_networks","notes","link"],"title":"PublicMerchantOut"},"PurchaseOut":{"properties":{"category":{"$ref":"#/components/schemas/Category"},"amount":{"type":"string","title":"Amount"},"date":{"type":"string","format":"date","title":"Date"},"merchant":{"anyOf":[{"$ref":"#/components/schemas/MerchantOut"},{"type":"null"}]}},"type":"object","required":["category","amount","date","merchant"],"title":"PurchaseOut"},"ResultOut":{"properties":{"rank":{"type":"integer","title":"Rank"},"card_id":{"type":"string","title":"Card Id"},"card_name":{"type":"string","title":"Card Name"},"network":{"$ref":"#/components/schemas/Network"},"annual_fee":{"type":"string","title":"Annual Fee"},"currency":{"type":"string","title":"Currency"},"points":{"type":"string","title":"Points"},"cents_per_point":{"type":"string","title":"Cents Per Point"},"estimated_value":{"type":"string","title":"Estimated Value"},"effective_rate":{"type":"string","title":"Effective Rate","description":"Value as a percentage of the purchase."},"behind_best":{"type":"string","title":"Behind Best","description":"Dollars less than the best pick earns on this purchase; 0 for the best pick."},"segments":{"items":{"$ref":"#/components/schemas/SegmentOut"},"type":"array","title":"Segments"},"reasons":{"items":{"type":"string"},"type":"array","title":"Reasons"},"freshness":{"$ref":"#/components/schemas/FreshnessOut"}},"type":"object","required":["rank","card_id","card_name","network","annual_fee","currency","points","cents_per_point","estimated_value","effective_rate","behind_best","segments","reasons","freshness"],"title":"ResultOut"},"SegmentOut":{"properties":{"spend":{"type":"string","title":"Spend"},"multiplier":{"type":"string","title":"Multiplier"},"is_bonus":{"type":"boolean","title":"Is Bonus"},"stacked":{"type":"boolean","title":"Stacked"}},"type":"object","required":["spend","multiplier","is_bonus","stacked"],"title":"SegmentOut"},"SourceOut":{"properties":{"name":{"type":"string","title":"Name","description":"Credit this name when you show the answer."},"url":{"type":"string","title":"Url"},"attribution":{"type":"string","title":"Attribution","examples":["Card rankings by Card Optimizer (https://cardoptimizer.app)"]},"note":{"type":"string","title":"Note"}},"type":"object","required":["name","url","attribution","note"],"title":"SourceOut"}}}}