Get Cheap Games Wishlist API

openapi: 3.2.0
info:
  title: getcheapgames Wishlist API
  description: Game key price comparison. All money is integer cents; rankings are on the price each store lists, without the service fee a marketplace adds at checkout.
  version: 0.1.0
tags:
- name: wishlist
paths:
  /api/account/wishlist:
    get:
      tags:
      - wishlist
      summary: Get Wishlist
      description: Every item, newest first, each priced for its own market.
      operationId: get_wishlist_api_account_wishlist_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WishlistOut'
  /api/account/wishlist/refs:
    get:
      tags:
      - wishlist
      summary: Get Refs
      description: 'The hearts'' shape: no prices, no cards, one small query.'
      operationId: get_refs_api_account_wishlist_refs_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WishlistRefsOut'
  /api/account/wishlist/platforms:
    get:
      tags:
      - wishlist
      summary: Get Platforms
      description: 'The platforms the game has an in-stock offer on, at a listed store and a

        real price, keyed for a region the country can use and, given a

        `currency`, priced in it: the only offers an alert in that money can

        ever count (`pricing.cheapest`), so the dialog offers no platform that

        could never send the email (owner, 09 Nov 2026: "Show only platforms

        where that game has offers for"). No session needed, as the game page

        is public.'
      operationId: get_platforms_api_account_wishlist_platforms_get
      parameters:
      - name: slug
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Slug
      - name: country
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
      - name: currency
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Currency
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertPlatformsOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/wishlist/add:
    post:
      tags:
      - wishlist
      summary: Post Add
      description: 'The game on the wishlist, in the market and money the visitor is on, or

        the item it already is: pressing the heart twice, or on two devices at

        once, makes one item and changes nothing. A target here is "Set alert"

        on a game the page took for not wishlisted; when it already was (added

        on another device meanwhile), the alert asked for is set on it all the

        same, as `/target` would, rather than dropped without a word.'
      operationId: post_add_api_account_wishlist_add_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WishlistItemOut'
  /api/account/wishlist/target:
    post:
      tags:
      - wishlist
      summary: Post Target
      description: 'Set the alert to `targetCents` in `currency`, or clear it (null); the game

        stays either way. The currency is the target''s, so the item is priced in

        it from now on.'
      operationId: post_target_api_account_wishlist_target_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WishlistItemOut'
  /api/account/wishlist/remove:
    post:
      tags:
      - wishlist
      summary: Post Remove
      description: 'Off the wishlist, with its alert history. 204 for an item already gone,

        so a double click is not an error; another account''s is never touched.'
      operationId: post_remove_api_account_wishlist_remove_post
      responses:
        '204':
          description: Successful Response
  /api/account/wishlist/mute:
    post:
      tags:
      - wishlist
      summary: Post Mute
      description: 'A price alert''s "Stop alerts" (one game) or "Stop all price alerts": the

        mute page''s button, and a mail client''s one-click unsubscribe, which posts

        `List-Unsubscribe=One-Click` here with the token in the address (RFC 8058;

        no same-origin check, as the token is the authority). `ok` for any token

        of ours, `invalid` for anything else. The token is read from the query by

        hand, so that no validation error ever repeats it.'
      operationId: post_mute_api_account_wishlist_mute_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusOut'
components:
  schemas:
    LogoOut:
      properties:
        src:
          type: string
          title: Src
        width:
          type: integer
          title: Width
        height:
          type: integer
          title: Height
      type: object
      required:
      - src
      - width
      - height
      title: LogoOut
      description: 'A game''s official logo (`services/game_logos.py`): the served path of its

        WebP, transparent and trimmed to the drawn pixels, and its size in pixels,

        so a page reserves the box before it loads.'
    StoreRefOut:
      properties:
        code:
          type: string
          title: Code
        name:
          type: string
          title: Name
        accent:
          type: string
          title: Accent
        kind:
          type: string
          title: Kind
      type: object
      required:
      - code
      - name
      - accent
      - kind
      title: StoreRefOut
      description: 'The store fields a client needs to render an offer.


        Embedded in each offer rather than referenced by id: it removes a

        client-side join and a second request, and six short records across a

        response is nothing next to the round trip it saves.'
    OfferCardOut:
      properties:
        store:
          $ref: '#/components/schemas/StoreRefOut'
        currency:
          type: string
          title: Currency
        listPriceCents:
          anyOf:
          - type: integer
          - type: 'null'
          title: Listpricecents
        feeCents:
          type: integer
          title: Feecents
        totalCents:
          type: integer
          title: Totalcents
        platform:
          type: string
          title: Platform
        inStock:
          type: boolean
          title: Instock
        regionLocked:
          type: boolean
          title: Regionlocked
          default: false
      type: object
      required:
      - store
      - currency
      - listPriceCents
      - feeCents
      - totalCents
      - platform
      - inStock
      title: OfferCardOut
      description: 'The part of an offer a CARD renders, and nothing else.


        A listing sends one of these per offer per game, and the cards read only

        four things from the set: the cheapest total, its currency and store, and

        the ceiling the saving badge is measured against. Sending the full

        `OfferOut` there put 24,901 bytes of offer into a 27,704-byte `/deals`

        response — **89% of the payload** — to compute those four numbers, and it

        sat on the critical path: nothing paints until it arrives.


        Field NAMES match `OfferOut` exactly so `bestOfferIn` and `priceSpread` in

        the browser work against either shape unchanged. The detail page keeps the

        full object, which is where the dropped fields are actually rendered.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    GameCardOut:
      properties:
        slug:
          type: string
          title: Slug
        title:
          type: string
          title: Title
        releaseYear:
          anyOf:
          - type: integer
          - type: 'null'
          title: Releaseyear
        releaseDate:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Releasedate
        publisher:
          type: string
          title: Publisher
        genres:
          items:
            type: string
          type: array
          title: Genres
        steamAppId:
          anyOf:
          - type: integer
          - type: 'null'
          title: Steamappid
        coverBase:
          anyOf:
          - type: string
          - type: 'null'
          title: Coverbase
        logo:
          anyOf:
          - $ref: '#/components/schemas/LogoOut'
          - type: 'null'
        priceHistory:
          items:
            type: integer
          type: array
          title: Pricehistory
          default: []
        kind:
          type: string
          title: Kind
          default: game
        isFree:
          type: boolean
          title: Isfree
          default: false
        freeToKeep:
          type: boolean
          title: Freetokeep
          default: false
        giveaway:
          anyOf:
          - $ref: '#/components/schemas/gcg__schemas__GiveawayOut'
          - type: 'null'
        playUrl:
          anyOf:
          - type: string
          - type: 'null'
          title: Playurl
        edition:
          anyOf:
          - type: string
          - type: 'null'
          title: Edition
        franchise:
          anyOf:
          - type: string
          - type: 'null'
          title: Franchise
        offers:
          items:
            $ref: '#/components/schemas/OfferCardOut'
          type: array
          title: Offers
          default: []
      type: object
      required:
      - slug
      - title
      - releaseYear
      - publisher
      - genres
      title: GameCardOut
      description: 'A game as a listing renders it.


        Declared rather than derived from `GameOut` so the wire shape of a listing

        is readable in one place. The fields a listing never fills — description,

        the edition family, package contents — are simply absent instead of being

        serialised as a screenful of nulls.'
    AlertPlatformsOut:
      properties:
        platforms:
          items:
            type: string
          type: array
          title: Platforms
      type: object
      required:
      - platforms
      title: AlertPlatformsOut
      description: '`GET /api/account/wishlist/platforms`: the platforms a game has an offer

        on that the reader''s country can use, in `gcg.platforms.PLATFORMS`

        order, for the alert dialog''s picker.'
    WishlistOut:
      properties:
        items:
          items:
            $ref: '#/components/schemas/WishlistItemOut'
          type: array
          title: Items
      type: object
      required:
      - items
      title: WishlistOut
      description: '`GET /api/account/wishlist`: every item, newest first.'
    WishlistItemOut:
      properties:
        id:
          type: integer
          title: Id
        game:
          $ref: '#/components/schemas/GameCardOut'
        targetCents:
          anyOf:
          - type: integer
          - type: 'null'
          title: Targetcents
        currency:
          type: string
          title: Currency
        country:
          type: string
          title: Country
        createdAt:
          type: string
          format: date-time
          title: Createdat
        best:
          anyOf:
          - $ref: '#/components/schemas/WishlistBestOut'
          - type: 'null'
        reached:
          type: boolean
          title: Reached
        alertPlatforms:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Alertplatforms
      type: object
      required:
      - id
      - game
      - targetCents
      - currency
      - country
      - createdAt
      - best
      - reached
      title: WishlistItemOut
      description: One wishlisted game, priced as a card for the item's own market.
    WishlistRefsOut:
      properties:
        items:
          items:
            $ref: '#/components/schemas/WishlistRefOut'
          type: array
          title: Items
      type: object
      required:
      - items
      title: WishlistRefsOut
      description: '`GET /api/account/wishlist/refs`: every item, newest first, as a ref.'
    WishlistRefOut:
      properties:
        id:
          type: integer
          title: Id
        slug:
          type: string
          title: Slug
        targetCents:
          anyOf:
          - type: integer
          - type: 'null'
          title: Targetcents
        currency:
          type: string
          title: Currency
        alertPlatforms:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Alertplatforms
      type: object
      required:
      - id
      - slug
      - targetCents
      - currency
      title: WishlistRefOut
      description: 'The light shape the hearts read: which games, by slug, and their targets.'
    StatusOut:
      properties:
        status:
          type: string
          enum:
          - ok
          - sent
          - expired
          - invalid
          - taken
          - too-many
          title: Status
      type: object
      required:
      - status
      title: StatusOut
      description: 'One word: the email routes say `sent` whatever the address''s state.'
    gcg__schemas__GiveawayOut:
      properties:
        platform:
          type: string
          title: Platform
        claimUrl:
          anyOf:
          - type: string
          - type: 'null'
          title: Claimurl
        endsAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Endsat
      type: object
      required:
      - platform
      title: GiveawayOut
      description: 'A giveaway on another store than Steam: what the claim button says and

        where it goes (`catalog.GIVEAWAY_ELSEWHERE`). Steam''s own is the game''s

        `free_to_keep`, whose link the client builds from the appid.'
    WishlistBestOut:
      properties:
        totalCents:
          type: integer
          title: Totalcents
        currency:
          type: string
          title: Currency
        store:
          $ref: '#/components/schemas/StoreRefOut'
      type: object
      required:
      - totalCents
      - currency
      - store
      title: WishlistBestOut
      description: 'The cheapest usable offer for the item (gcg/wishlist/pricing.py): in

        stock, keyed for a region covering the item''s country, fees included, in

        the item''s own currency. Never converted.'