RightCard

Which of the given cards earns the most at a store (merchant) or for a spend category, today. Returns the card, the honest rate, why, and caveats (merchant-code traps, activation, ties). Base rates + rotating bonuses + built-in card benefits only; a user's personal bank offers live on their phone and are not consulted here.

{
  "type": "object",
  "properties": {
    "wallet": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Card ids the person holds (from search_cards)."
    },
    "merchant": {
      "description": "Store name, e.g. 'Costco', 'Whole Foods', 'Uber'. Use this OR category.",
      "type": "string"
    },
    "category": {
      "description": "Spend category when there is no specific store.",
      "type": "string",
      "enum": [
        "dining",
        "grocery",
        "travel",
        "gas",
        "online",
        "drugstore",
        "transit",
        "streaming",
        "general"
      ]
    },
    "valuation": {
      "default": "cash",
      "description": "'cash' counts every point at 1¢ (default). 'points' values points per program at conservative travel values.",
      "type": "string",
      "enum": [
        "cash",
        "points"
      ]
    },
    "on": {
      "description": "Date (YYYY-MM-DD, UTC) for rotating windows; defaults to today.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "chosen_categories": {
      "description": "For choose-your-category cards (Citi Custom Cash, BofA Customized, Venmo): card id → the categories the person set.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "dining",
            "grocery",
            "travel",
            "gas",
            "online",
            "drugstore",
            "transit",
            "streaming",
            "general"
          ]
        }
      }
    }
  },
  "required": [
    "wallet"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The store's reward category as RightCard's directory files it, its merchant type, and the merchant-code caveat when a category bonus usually will not post there (superstores like Walmart/Target, warehouse clubs like Costco/Sam's). Same ranking the app uses.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 2
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Search RightCard's catalog by card or issuer name to get the ids to pass into best_card. Verified cards first; unverified cards are flagged, never hidden.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2
    },
    "issuer": {
      "type": "string"
    },
    "limit": {
      "default": 12,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Everything RightCard knows about one card: rates by category, base rate, currency, annual fee, verification status, live rotating windows, and the choose-your-category spec if it has one.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Live and upcoming rotating-category windows (Freedom Flex, Discover it, Citi Dividend…) and permanent merchant benefits, from the same verified data as the app. Optionally filter by card id.

{
  "type": "object",
  "properties": {
    "card_id": {
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}