ManaVault API

ManaVault API v1.0 Documentation

1. Authorization

Authorization parameters are available at ManaVault Profile if API Access is obtained from Admin.

Each request except authorization is required to include 'access_token' parameter obtained from Authorization.

Access tokens are valid for 10 minutes from authorization and are not renewed if valid token exists.

API call number is limited to 600 requests per 10 minutes.

Explorer access:

Get access token

Authorization request:

    POST https://api.manavault.pl/v1.0/authorize
    Form data:
        client_id=XXXXXXXXXX
        client_secret=YYYYYYYYYY

Curl Example:

    curl -d "client_id=XXXXXXXXXX&client_secret=YYYYYYYYYY" https://api.manavault.pl/v1.0/authorize

Example response:

{
    "data": {
        "access_token": "generated_access_token",
        "valid_until": "2024-11-21 06:23:22"
    }
}

Example headers:

    HTTP/1.1 200 OK
    Date: Wed, 03 Oct 2018 20:05:46 GMT
    Server: Apache/2.2.22 (@RELEASE@)
    X-Powered-By: PHP/5.5.38
    Content-Length: 166
    Connection: close
    Content-Type: application/json

2. Endpoints available:

All available methods are listed below starting with •

(code) or (id) parameter within methods is required.

+ is an additional `fields` parameter and is included by adding ?fields=field1,field2,... to request url (see examples below).

Parameters can be user for fitering results. E.g. /edition/GRN/?fields=cost(2W) will return cards from Guilds of Ravnica having mana cost 2W.

• Endpoints list:

        • editions

        • edition/(code)
            + name (..)
            + number (..)
            + cost (..)
            + type (..)
            + rarity (..)
            + cmc (..)
            + oracle (..)
            + artist (..)
            + flavor (..)
            + multiverse_id (..)

        • edition/(code)/prices
            + currency (PLN/EUR/USD)
            + mcm_avg
            + mcm_trend
            + mcm_foil_avg
            + mcm_foil_trend
            + multiverse_id

        • multiverse/(id)
            + name
            + number
            + cost
            + type
            + rarity
            + cmc
            + oracle
            + artist
            + flavor

        • multiverse/(id)/prices
            + currency (PLN/EUR/USD)
            + mcm_avg
            + mcm_trend
            + mcm_foil_avg
            + mcm_foil_trend
            + edition
            + edition_code
            + number

All available requests can be tested using ManaVault API Explorer

3. Endpoint request examples:

Example headers:

        HTTP/1.1 200 OK
        Date: Wed, 03 Oct 2018 21:14:54 GMT
        Server: Apache/2.2.22 (@RELEASE@)
        X-Powered-By: PHP/5.5.38
        Call number: 95
        Call limit: 600
        Connection: close
        Transfer-Encoding: chunked
        Content-Type: application/json

• List available editions:

    Request:
        GET https://api.manavault.pl/v1.0/editions?access_token=generated_access_token

    Response:
    {
        {
            "code": "GRN",
            "name": "Guilds of Ravnica",
            "released": "2018-10-05",
            "type": "Expansion"
        },
        {
            "code": "C18",
            "name": "Commander 2018 Edition",
            "released": "2018-08-10",
            "type": "Commander"
        },
        {
            "code": "M19",
            "name": "Core Set 2019",
            "released": "2018-07-13",
            "type": "Core Set"
        },
        {...}
    }

• List all cards from Guilds of Ravnica with basic data:

        Request:
            GET https://api.manavault.pl/v1.0/edition/GRN?access_token=generated_access_token

        Response:
        [
            {
                "number": "1",
                "name": "Blade Instructor"
            },
            {
                "number": "2",
                "name": "Bounty Agent"
            },
            {
                "number": "3",
                "name": "Candlelight Vigil"
            },
            {
                "number": "4",
                "name": "Citywide Bust"
            },
            {...}
        ]

• List all cards from Guilds of Ravnica with full data:

        Request:
            GET https://api.manavault.pl/v1.0/edition/GRN/?fields=name,number,cost,type,rarity,cmc,oracle,artist,flavor,multiverse_id&access_token=generated_access_token

        Response:
        [
            {
                "number": "1",
                "name": "Blade Instructor",
                "cost": "2W",
                "type": "Creature — Human Soldier",
                "rarity": "Common",
                "cmc": "3",
                "oracle": "Mentor (Whenever this creature attacks, put a +1/+1 counter on target attacking creature with lesser power.) ",
                "artist": "Zoltan Boros",
                "flavor": "\"Watch carefully. The gap between death and victory is thinner than your blade.\"",
                "multiverse_id": "452751"
            },
            {
                "number": "2",
                "name": "Bounty Agent",
                "cost": "1W",
                "type": "Creature — Human Soldier",
                "rarity": "Rare",
                "cmc": "2",
                "oracle": "Vigilance {T}, Sacrifice Bounty Agent: Destroy target legendary permanent that's an artifact, creature, or enchantment.",
                "artist": "Randy Vargas",
                "flavor": "\"Lately I've seen the biggest bounties of my career—and for the biggest names.\"",
                "multiverse_id": "452752"
            },
            {...}
        ]

• List all Planeswalkers from Worldwake with full data:

        Request:
            GET https://api.manavault.pl/v1.0/edition/WWK/?fields=name,number,cost,type(Planeswalker),rarity,cmc,oracle,artist,flavor,multiverse_id&access_token=generated_access_token

        Response:
        [
            {
                "number": "31",
                "name": "Jace, the Mind Sculptor",
                "cost": "2UU",
                "type": "Legendary Planeswalker - Jace",
                "rarity": "Mythic Rare",
                "cmc": "4",
                "oracle": "+2: Look at the top card of target player's library. You may put that card on the bottom of that player's library.
                            0: Draw three cards, then put two cards from your hand on top of your library in any order.
                            -1: Return target creature to its owner's hand.
                            -12: Exile all cards from target player's library, then that player shuffles his or her hand into his or her library.",
                "artist": "Jason Chan",
                "flavor": "",
                "multiverse_id": "195297"
            }
        ]

4. Example error responses

Invalid access token:

    Headers:
        HTTP/1.1 403 Forbidden
        Date: Wed, 03 Oct 2018 21:31:52 GMT
        Server: Apache/2.2.22 (@RELEASE@)
        X-Powered-By: PHP/5.5.38
        Content-Length: 32
        Connection: close
        Content-Type: application/json

    Response:
        {
            "error":"Invalid access_token"
        }

Invalid field:

    Headers:
        HTTP/1.1 400 Bad Request
        Date: Wed, 03 Oct 2018 21:29:41 GMT
        Server: Apache/2.2.22 (@RELEASE@)
        X-Powered-By: PHP/5.5.38
        Call number: 98
        Call limit: 600
        Content-Length: 41
        Connection: close
        Content-Type: application/json

    Response:
        {
            "error":"Unknown field: invalid_field."
        }

To many requests:

    Headers:
        HTTP/1.0 429 Too Many Requests
        Date: Wed, 03 Oct 2018 21:53:52 GMT
        Server: Apache/2.2.22 (@RELEASE@)
        X-Powered-By: PHP/5.5.38
        Call number: 601
        Call limit: 600
        Content-Length: 60
        Connection: close
        Content-Type: application/json

    Response:
        {
            "error":"API request limit reached. Retry in 368 seconds."
        }