CUA00001 - A Cross Universe API by Psychpsyo

Welcome to the Cross Universe API documentation page.
This API lets you access the images for all English and Japanese Cross Universe cards, as well as card metadata.
The entire API runs under https://crossuniverse.psychpsyo.com.
If any of it breaks, misbehaves or serves incorrect data, please tell me.
Note that all card IDs ever handled by this API do not include the leading "CU", meaning that the ID for (for example) 'Stone Circle' is "I00001", not "CUI00001"

Contents

  1. Card Images
  2. Card Data / Metadata
  3. Card Searching
  4. Enums

Card Images

Card images are available under /images/cards/LANG/CARD_ID.jpg where LANG is the language and CARD_ID is the ID of the card.
So, if you wanted to query the English image for 'Rei, the Summoner', you'd query /images/cards/en/U00031.jpg.
LANG can be any of the following options:

If the card doesn't exist, a 404 is returned.


Card Data / Metadata

To get almost any other bit of info on a card, there is the /cardInfo endpoint.
You query it by passing lang and cardID as the query parameters of a GET request.
An example would be to query /cardInfo/?lang=en&cardID=U00107, to get info on Pandemic Rat. (the card with ID U00107)
lang once again accepts en and ja as values, giving you the card info in English or Japanese, respectively.
The return value of this is a JSON object with the following structure:

Name Type Description
cardID string The ID of the card. (i.e. U00161, S00028...)
name string The name of the card in the requested language, without variant indicator.
(Meaning that both 'Cheering Angel Token A' and 'Cheering Angel Token B' will just be 'Cheering Angel Token')
Note that, for Japanese names, these try to keep the spacing of the name as it is on the card. (regular vs full-width vs no spaces)
level number The base level of the card.
cardType string The type of the card, as a string. This can be any card type, with the exception of "spell" and "item" as this will always give the more specific type of spell or item.
Note that these values are not localized, meaning they will be these exact strings, even when querying the data in Japanese.
types array[string] An array of strings, specifying the base types of the card. Card types are listed here.
Note that these values are not localized, meaning they will be these exact strings, even when querying the data in Japanese.
effectsPlain string The card's text box, in plain text.
The text is returned with new lines and indentation, intended to be viewed in a font that keeps Japanese characters full-width and ideally has the same width for spaces and '['.
The latter is only required for proper indentation of given effects. (The ones with the large brackets around them, like on 'Medusa's Shield') Note that the "Idea: name" in the bottom right corner of cards that won card contests is not returned here.
deckLimit number The amount of times you can add the card to a deck.
For cards with a deck limit of infinite, this value is 50, as that is the highest number of cards in a legal deck.
releaseDate string The date that the card got released, formatted as YYYY-MM-DD. For cards where I currently do not have the release date, this property is not present.
counterMentions array[string] An array of strings, indicating what counters the card mentions. All counters are listed here.
Note that those values are not localized, meaning they will be those exact strings, even when querying the data in Japanese.
typeMentions array[string] An array of strings, indicating what types the card directly mentions. (i.e. "Light-type cards", "Machine and Angel-type unit(s)"). All types are listed here.
Note that those values are not localized, meaning they will be those exact strings, even when querying the data in Japanese.
visibleCards array[string] This array contains the IDs for all cards which appear as cards on the given card. Examples of this are 'Akashic Records' and 'Future Foresight' as they both show other cards in their illustration.
Note that a card like 'Amnesia Incantation' however, will not list "U00031" (Rei, the Summoner) here since, while she does appear in the illustration, it is not her card that appears.
cardMentions array[string] This array contains the IDs for all cards which are mentioned on the given card, in it's text box.
Note that even 'trivial' cases are included here, such as 'Amnesia's Arrival' or 'Offering of the Soul' which both mention themselves.
mentionedOn array[string] This array contains the IDs for all cards that the given card is mentioned on. (This once again includes the trivial cases mentioned above.)
visibleOn array[string] This array contains the IDs for all cards which depict the given card in their illustration.
characters array[string] A list of what characters are visible in the illustration of the card. A list of all values that this can contain is found here.
illustrator string The name of the person who illustrated the card art. For cards where the illustrator is not specified on the card, this property is not sent.
It's value can be any of these strings.
Note that those values are not localized, meaning they will be these exact strings, even when querying the data in Japanese.
idea string The name of the person who came up with the card's idea during one of the card text contests. For cards where no one is credited on the card, this property is not sent.
(The only exception to this being tokens that were originally mentioned on contest winning cards.)
It's value can be any of these strings.
Note that those values are not localized, meaning they will be these exact strings, even when querying the data in Japanese.
variantOf string What 'card' the given card is a variant of. This is usually the card's name in camel case. (i.e. illusionSoldierToken)
Note that this does not identify any of the variants as the base card, as they all have the same name.
If the card is not one of multiple variants, this property is not sent.
variant string Which variant the given card is, as an upper case letter. The first variant of a card will be "A", the second one "B", the third one "C" and so on.
Their main purpose is to make the different variants distinguishable by name alone. In that case they are appended to the regular name of the card.
In English, there is a space in between while Japanese omits the space. Japanese also omits these entirely when specifying the hiragana name for a card.
Note that as an exception to this, the official Japanese card data lists T00008 as プラントトークン, instead of プラントトークンA.」.
legacyExID string The EX ID of the given card, being of the form CUS-EX000.
These IDs were given to cards where the illustration was made by Barten, up until they were replaced with regular card IDs on the 8th of April, 2019.
To my knowledge, only the 10 spell cards S00072-S00081 ever had these. For any card that was not in the EX series, this property won't be sent.
Note that these have basically no practical usage and are just included for archival purposes.

Japanese Specific Values

These values will only show up when requesting card data in Japanese as they do not translate to English.

Name Type Description
nameHiragana string The card's name in hiragana, without variant indicator. Note that this may sometimes be missing from very new cards for a while.
The spacing in the name is consistent with that on the cards, meaning that whether or not regular, full-width or no spaces are used between words, depends on how the regular name is written on the card.
For cards that include an & in their name, (such as ガード&ドロー) it is written as 「あんど」.
nameFurigana array[object] The furigana that go along with the Japanese card name, as given on the card itself. The list is comprised of objects, each of which have a 'text' and 'end' property.
text is simply a string, containing that group of furigana. end is the index one after the last character in the name of the card that corresponds to the group of furigana.
Note that initial characters without furigana are represented by an empty group, as well as gaps between groups of furigana. (text being empty string here)
This however does not apply to trailing characters without furigana in the base string.
If the card has no furigana, this property will not be sent.
These are structured this way since they now lend themselves nicely to walking the string, inserting the groups of furigana as you pass them, while always starting a new one when the last one ended.

Error Handling

Currently if the server fails to process the request, for any reason, it returns the error code 500.
This is subject to change and will probably be replaced with more descriptive error codes and messages in the future.


Card Searching

The card search API is used to get a list of cards that match certain criteria.
It is accessed though the /cardInfo endpoint by sending a POST request, passing the search query as JSON it the POST body.
The query is a JSON object with the following properties: (Note that any of these properties can be omitted for them to be ignored in the search.)

Name Type Description
name string Search for cards where the card name includes this string. This automatically searhes both the English and Japanese card names.
For the Japanese names, the hiragana representation of the name is also searched.
textbox string Search for cards that contain the given string in their textbox.
cardID string Search for cards with the given ID.
This does not require a full card ID. If only "5" is given, it will return U00005, S00005, U00005 and T00005.
Similarly, if this is "U", it will return all unit cards. Any card ID passed to this can have the leading "CU", as this will simply be ignored.
levels array[number] Search for cards with the given levels.
To search for cards that have a level of ? (like 'Phantom Memory Token'), include -1 in the list.
types array[string] Search for cards with the given types. The types can be any of these values.
cardTypes array[string] Search for cards of the given card types. The types can be any of these values.
deckLimit string Search for cards that can be included in the deck a certain amount of times. The possible values are "less", "more" and "inf".
"less" and "more" are both relative to the default of 3, while "inf" just gives cards that can be included an infinite number of time.
Note that "more" will not include those cards, despite infinite being more than 3.
Another option is to pass any number as a string. (i.e. "3", "1"...) This will search for cards that can be included exactly that number of times.
Passing empty string will cause the deck limit to be ignored, any other value will not return any cards.
counters array[string] Search for cards that mention any of the given counters. A list of all counters can be found here.
attackMin number Search for cards that have at least this much Attack. When passing -1, that also means that this property will be ignored.
attackMax number Search for cards that have at most this much Attack. When passing -1, that also means that this property will be ignored.
defenseMin number Search for cards that have at least this much Defense. When passing -1, that also means that this property will be ignored.
defenseMax number Search for cards that have at most this much Defense. When passing -1, that also means that this property will be ignored.
releaseDate string Search for cards that were released on this day. The string is of the form YYYY-MM-DD.
illustrator string Search for cards that were illustrated by this person. illustrator can be any of these values.
idea string This is the name of a contest winner and will search for cards that they came up with that then won the card contest. It can be any of these values.
Note that this will also return tokens that were originally mentioned on the winning cards.
characters string Search for cards that include the given characters in their illustration. Character Names are separated by commas and can be in English or Japanese.
Note that substrings are also matched and the matching is case sensitive.
In addition to that, some characters have alternate or not well known names, meaning that you shouldn't use this to find all cards with a specific character.
exactCharacters array[string] Search for cards that include the given characters in their illustration. The list can contain any of these values.
Note that all cards that depict any of the passed characters will be returned and, if sortBy isn't specified, they will be ordered by how many are depicted.
sortBy string Indicates what the returned list of cards should be sorted by. Possible values are:
  • level - cards are sorted by level, in ascending order. A level of ? will be sorted before 0 and cards with the same level are sorted by name.
  • name - cards are sorted by their name, check the language property for more details
  • releaseDate - cards are sorted by their release date, in descending order. Cards with no logged release date are sorted last and cards released on the same day are sorted by their card IDs.
  • cardID - cards are sorted by their IDs, in ascending/alphabetical order.
  • attack - cards are sorted by their attack, in descending order. Spells and items, as well as units with the same amount of attack, are sorted by level, then name.
  • defense - cards are sorted by their defense, in descending order. Spells and items, as well as units with the same amount of defense, are sorted by level, then name.
If this property is not specified, cards are sorted by relevancy to the query instead.
language string A string, indicating what language to use when sorting cards by name. Possible values are "ja" and "en", with the default being "en".
In English, cards are sorted alphabetically, while in Japanese they are sorted by gojūon, based off of their name in hiragana.

The Response

The response is a list of objects, in JSON format, containing the following properties:

Name Type Description
cardID string The card's ID.
cardType string The card type of the card. All card types are listed here.

Error Handling

Currently, if the server encounters an error while processing you request, it will still respond with a valid list, though that list will only contain 3 copies of U00107.
This should in theory never happen except for cases where your query is not valid json.
Do not that you can currently use a check for this specific response to detect errors without worrying since a correct response will never return more than one copy of any given card.
That said, this will likely change in the near future as I clean up the API.


Enums

Card Types

The following card types exist:

Counters

The following counters exist:

Types

The following types exist:

Characters

The following is a list of all characters that appear on cards:
(The only exception being completely unnamed regular animals such as the birds in 'Road to the Heavens')

Illustrators

The following people have been credited for their illustrations on cards so far:

Card Contest Winners

The following people have been credited for card ideas on cards, as they have won a card contest in the past: