API Documentation

Moodiest offers a public JSON API for searching and filtering Mood Swings Data. It's modelled on Scryfall's API, so if you've ever used that, most of this will feel familiar.

Overview

Every response comes in one of three shapes: a single card, a list, or an error.

Since the whole dataset is currently a fixed set of 134 card printings, a list is just a single page: has_more is always false and next_page is always null.

Card

Represents the printing of one card, the object every endpoint below ultimately returns, either alone or inside a list's data array. Field names follow Scryfall's terminology where Mood Swings has an equivalent concept (e.g. name, rarity, colors, oracle_text, set).

Field	Type	Details
`object`	string	Always `card`
`id`	UUID	The printing's UUID. What `/api/cards/:id` looks up
`oracle_id`	UUID	The mood's UUID, stable across reprints (shared by both Love printings)
`name`	string	The mood's name
`released_at`	string	The printing's set's release date (`YYYY-MM-DD`)
`uri`	string	This object's own API URL
`moodiest_uri`	string	The card's human-facing page on Moodiest
`colors`	array	WUBRG color codes, e.g. `["W"]`
`oracle_text`	string	The effect, markup-stripped plain text. Empty for vanilla moods
`rarity`	string	`common`, `uncommon`, `rare`, or `mythic`
`value`	string	The printed value string, e.g. `[3]/[6][1]`
`base_value`	int	The value on the top right dice
`secondary_value`	int, nullable	The value on the bottom left dice, if any
`has_secondary`	bool	Whether the card has a secondary value
`dice_color`	string	`white` (fixed value) or `black` (value can change)
`timing`	array	Effect trigger codes, i.e. `to_play`, `in_play`, `after_playing`
`has_reminder_icon`	bool	Whether the printed card carries the `!` icon
`set`	string	Lower-cased set code
`set_name`	string	The set's name
`lang`	string	Language code
`collector_number`	string	The printing's collector number
`artist`	string	The printing's credited artist
`image_uris`	object	The card's image, a single size under the `normal` property
`is_headliner`	bool	Whether a printing is the set's headliner card
`notes`	array	The mood's rules clarifications

List

Represents a page of cards.

Field	Type	Details
`object`	string	Always `list`
`total_cards`	int	The number of objects in `data`
`has_more`	bool	Always `false`
`next_page`	string, nullable	Always `null`
`data`	array	`card` objects
`warnings`	array, optional	List of query terms that were ignored

Error

Represents an error.

Field	Type	Details
`object`	string	Always `error`
`status`	int	The HTTP status, repeated in the body
`code`	string	A machine-readable error code
`type`	string, optional	A code sub-type, currently only `ambiguous` when a named lookup matched more than one card
`details`	string	A human-readable message
`warnings`	array, optional	List of query terms that were ignored

Example

{
  "object": "error",
  "status": 400,
  "code": "bad_request",
  "details": "All of your terms were ignored.",
  "warnings": [
    "Invalid expression “c:z” was ignored. Unknown color “z”"
  ]
}

Endpoints

API base URL: https://moodiest.app

`/api/cards/:id`

Look up one printing by its UUID. Returns: card.

Parameter	Type	Details
`id`	UUID	The printing's UUID

Example request

Select the request above to run it live.

`/api/cards/:set/:number`

Look up one printing by its set code and collector number. Returns: card.

Parameter	Type	Details
`set`	string	Set code, case-insensitive
`number`	string	Collector number

Example request

Select the request above to run it live.

`/api/cards/random`

Draw one random card, optionally from the cards matching a q query. Returns: card.

Parameter	Type	Details
`q`	string, optional	A search query (see the Syntax Guide). Make sure the value is properly encoded. Draws from all cards if omitted

Example request

Select the request above to run it live.

`/api/cards/search`

Search cards with the same query syntax as the search bar. Returns: list.

Parameter	Type	Details
`q`	string	A search query (see the Syntax Guide). Make sure the value is properly encoded

Example request

Select the request above to run it live.

`/api/cards/named`

Look up one card by name. Provide exactly one of exact or fuzzy. Returns: card.

Parameter	Type	Details
`exact`	string, optional	A full, case-insensitive name match
`fuzzy`	string, optional	A substring match, falling back to nearest-spelling if nothing matches

Example request

Select the request above to run it live.