# Óskalisti: Magic: The Gathering card search over TCGísland's stock

> An independent, unofficial site that follows the public Magic: The Gathering catalog of
> TCGísland (https://tcgisland.is/mtg), a card store in Iceland: what is in stock, prices in
> Icelandic krónur (ISK) and how they change. Use it to search cards, check a decklist against
> the store's stock, find cards the store has never had, and watch cards to get an email when
> they come in. It is not affiliated with, endorsed by or run by TCGísland. Nothing can be bought
> here: cards are bought from the store, at each listing's `buyUrl`.

## Before you answer anyone

- **Not the store.** Don't present this site as TCGísland or as its official site. Say the data
  comes from TCGísland's public catalog, and that buying happens in their store.
- **Buying:** link to the listing's `buyUrl`, the store's product page with its add-to-cart
  button. There is no cart, checkout or payment here.
- **Freshness:** the store's catalog is read about once an hour; `GET https://spil.sjomli.is/api/meta` says
  when it last was. Price and stock may have changed since. The store has the final word.
- **Quantities:** the store doesn't publish them. "In stock" means at least one copy.
- **Prices** are whole Icelandic krónur (ISK), the store's own. Card data (rules text, legality)
  comes from Scryfall.
- The website is in Icelandic. The API and these notes are in English.

## Use it as tools (MCP)

An MCP server, no sign-in: `https://spil.sjomli.is/mcp` (Streamable HTTP). Add it as a custom connector in
Claude, ChatGPT, Cursor or any MCP client. Read-only tools: `search_cards`,
`search_cards_not_in_store`, `get_card`, `get_printing`, `get_price_history`,
`price_movers`, `check_decklist`, `store_status`. They answer like the HTTP API below,
trimmed, with every listing's `buyUrl`. The wishlist is only in the HTTP API, with a key.

## API

Base URL: https://spil.sjomli.is. JSON over HTTPS, no key needed except for the wishlist.

- [OpenAPI 3.1 spec](https://spil.sjomli.is/api/openapi.json): every endpoint, parameter and response shape
- [Interactive docs](https://spil.sjomli.is/api/docs)

### Search the store's catalog

`GET https://spil.sjomli.is/api/search?q=<query>&sort=price&pageSize=20`

One result per printing (set and collector number), each with its listings (normal, foil,
etched): price, whether it's in stock, and `buyUrl`. `sort`: `name`, `price` (cheapest
in stock first), `manaValue`, `set`, `recent` (last stock change). `group=card` merges a
card's printings. `page`, `pageSize` up to 100. Sold-out and delisted cards are included unless
the query says `stock:in`.

Examples:
- `https://spil.sjomli.is/api/search?q=!%22Sol%20Ring%22%20stock%3Ain&sort=price`: cheapest Sol Ring in stock
- `https://spil.sjomli.is/api/search?q=t%3Aelf%20c%3Ag%20mv%3C%3D2%20f%3Acommander%20stock%3Ain`: cheap green elves for Commander
- `https://spil.sjomli.is/api/search?q=id%3C%3Drg%20o%3A%22deals%20damage%22%20price%3C%3D500%20stock%3Ain`: red-green burn under 500 kr

### Query syntax

A subset of Scryfall's (https://scryfall.com/docs/syntax). Terms are ANDed; `or`, `-term` and
`( )` work as on Scryfall.

| Syntax | Meaning |
|---|---|
| `bolt`, `"lightning bolt"` | name contains |
| `!"Sol Ring"` | exact name |
| `o:draw`, `o:"draw a card"` | rules text contains (`~` is the card's name) |
| `t:legendary t:creature` | type line contains |
| `c:wu`, `c=wu`, `c<=wu`, `c:c`, `c:m` | colors (`:` means at least) |
| `id:wub` | color identity fits (commander) |
| `mv<=3` | mana value |
| `m:{R}{R}`, `m:2WW` | mana cost contains |
| `f:commander`, `banned:modern` | format legality |
| `price<=1000` | price in ISK |
| `stock:in`, `stock:out` | in stock now / sold out |
| `r:mythic`, `r>=rare` | rarity |
| `s:mh3` | set code |
| `is:foil`, `is:etched`, `is:nonfoil` | finish |
| `a:"rebecca guay"` | artist |
| `pow>=4`, `tou<2`, `loy=3` | power, toughness, loyalty |
| `o:/^flying$/` | regex, after `o:`, `t:`, `name:`, `a:` |

A query that doesn't parse returns 400 with `error.code: "query_syntax"` and the position.
`POST /api/search` takes the same as a structured `filter` (see the spec).

### Cards the store has never had

`GET https://spil.sjomli.is/api/search/missing?q=<query>`: cards no store listing has ever pointed at, from
every paper Magic card, with Scryfall's picture. Same syntax; price, stock, finish and rarity are
ignored. Useful for "the store doesn't have it, but you can watch for it".

### Cards and printings

- `GET https://spil.sjomli.is/api/cards/{oracleId}`: a card's rules text, legalities and every printing the store has listed
- `GET https://spil.sjomli.is/api/printings/{scryfallId}`: one printing, with its stock history
- `GET https://spil.sjomli.is/api/cards/{oracleId}/prices`, `GET https://spil.sjomli.is/api/printings/{scryfallId}/prices`: price
  changes over 7, 30 and 90 days, lowest and highest since first seen
- `GET https://spil.sjomli.is/api/prices/movers?days=7&direction=down`: biggest price changes; `minPriceIsk`
  leaves out cheap cards

Ids are Scryfall's: `oracleId` for a card, `scryfallId` for a printing.

### Check a decklist

`POST https://spil.sjomli.is/api/decklist/check` with the list as the body, `Content-Type: text/plain`, one card
per line, up to 500 lines. Moxfield, Archidekt, MTGA and plain lists work (`4 Lightning Bolt`,
`1 Sol Ring (C21) 263 *F*`, section headers like `Sideboard`). Each line comes back as
`in_stock`, `sold_out`, `not_carried` (a real card the store has never had) or
`unknown_card` (no card by that name), with the store's printings and their `buyUrl`s.

To price a deck, take the cheapest in-stock listing per line times its quantity, and say it's a
floor: the store may not have as many copies as the deck needs.

### Wishlist and restock emails

People keep a wishlist of cards and saved searches, and get an email when one comes into stock
or, for a card entry, drops under a price they set. Cards the store has never had can go on it
too: the email comes when the store lists them.

To use someone's wishlist, ask them for an **API key**: they sign in at https://spil.sjomli.is/oskalisti (an
emailed link, no password), make a key under "Aðgangslyklar" and give it to you. Send it as
`Authorization: Bearer osk_...`. It acts for them until they remove it, but can't make keys or
delete the account. Don't ask for their email inbox or the sign-in link.

- `GET https://spil.sjomli.is/api/wishlist`: their entries, each with what's in stock now
- `POST https://spil.sjomli.is/api/wishlist` with `{"kind": "card", "oracleId": "..."}`: watch a card, in any printing.
  Optional: `scryfallId` (one printing), `finish` (`normal`, `foil`, `etched`),
  `maxPriceIsk` (only at or under this price), `notifySoldOut`
- `POST https://spil.sjomli.is/api/wishlist` with `{"kind": "search", "name": "Cheap elves", "query": "t:elf price<=200"}`:
  a saved search, emailed when new printings match
- `PATCH` / `DELETE https://spil.sjomli.is/api/wishlist/{id}`: change or remove an entry
- `POST https://spil.sjomli.is/api/wishlist/decklist` with a decklist as `text/plain`: watch every card in it
  that isn't in stock
- `GET https://spil.sjomli.is/api/notifications`: what they've been told, newest first
- `GET` / `PATCH https://spil.sjomli.is/api/me`: email on or off, each scrape or a daily digest

Adding a card that's already in stock doesn't email; the email comes on the next change.

## Being a good guest

This runs on a small home server. Keep to a few requests a second, and use `pageSize` instead of
many small pages. Please don't scrape the store through this site.

## Website

- [Search (Yfirlit)](https://spil.sjomli.is/): the catalog with filters
- [Decklist (Dekk)](https://spil.sjomli.is/dekk): paste a list, see what the store has
- [Wishlist (Óskalisti)](https://spil.sjomli.is/oskalisti)
- [Price changes (Verðbreytingar)](https://spil.sjomli.is/verdbreytingar)