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.
effects array[object] The effects within the card's text box, as individual objects.
All of them contain a text property which is the effect's text, formatted the same way it is in effectsPlain.
Additionally, they have a type property, indicating what type of effect it is. All types are listed here.
For trigger abilities, the object contains an additional property, mandatory, which is a boolean, specifying whether or not the activation is forced or not.

Note that for cards that have effects contained within other effects, those inner effects are part of the main effect and not currently described individually.
An example of this would be 'Medusa's Shield', where its second effect contains another effect, within brackets.
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.
occasions array[object] The occasion(s) for which the card was released.
If there was no special occasion to go along with the card's release, the list is empty.
The objects themselves have a "type" property, indicating the type of occasion. This property can be any of the following:
  • cardMilestone (Cards that were released because a specific number of total cards has been reached.)
    These have an additional "amount" property of type number, specifying what amount of cards was reached.
  • event (Cards released to celebrate general events. This includes holidays, dates or commemorative cards.)
    These have additional "event" and "eventType" properties of type string, specifying the specific event.
    "eventType" can be any of the following:
    • commemoration
    • holiday
    • specialDay
    "event" can be any of the following:
  • ideaContest (Cards that were released as the result of an card text contest.)
    These have an additional "contest" property of type number, that specifies which idea contest it was. (starting at 1)
  • siteAnniversary (Cards that were released in celebration of the anniversary of the official website.)
    These have an additional "years" property of type number that specifies what anniversary it was.
  • siteVisitors (Cards that were released to celebrate a milestone number of website visitors on the official site.)
    These have an additional "amount" property of type number, indicating the amount of site visitors.
  • twitterFollowers (Cards that were released to celebrate a specific number of twitter followers on the official twitter account.)
    These have an additional "amount" property of type number, indicating the amount of followers.
novelAppearances array[object] A list of novel chapters that the card appeared in, along with a list of which characters owned the card in those chapters.
The objects each have a chapter property which specifies what chapter they are referring to, along with an owners property which is a list of strings, specifying the characters that owned the card in said chapter.
All characters are listed here. Cards are tagged for being in a chapter if their effects happen, they are interacted with, mentioned or the main character on the card appears as a character. (as is the case with Dorothy)
Chapters for the main novel are formatted as "N1-Ex-Cy" where x is the episode and y is the chapter. No cards appear in the prologue and the epilogue is treated as episode 10, chapter 8.
Chapters for the spin-off are formatted as "N2-Cx" where x is the chapter, as it is currently not divided into episodes.
Note: these are still a work-in-progress and so far only cards from the first four chapters of the main novel and cards from the spin-off have been tagged.

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

The server will return error code '400 Bad Request' when requesting cards that do not exist or in languages other than English or Japanese.
The same error code will be returned when either the cardID or lang properties are omitted.
For unexpected errors encountered in the processing of your request, a '500 Internal Server Error' will be sent.


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 searches 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 might change at some point when I clean up the API.


Enums

Card Types

The following card types exist:

Counters

The following counters exist:

Card Effects

The following types of card effects 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:

Novel Characters

These characters appear in the official novels and own/use cards: