← Back

Recommander API

Recommander maintains a public-facing API for card recommendations. This page documents the available endpoints, request and response formats, error codes, and example usage.

The public release is hosted at https://api.recommander.cards/public-release. All endpoint paths below are relative to that base URL.

This API is intended for use by third-party developers, content creators, and anyone else interested in integrating Recommander's card recommendations into their own projects. Whether you're creating a deck-building tool, a content website, or just want to experiment with the data, the API provides a way to access Recommander's insights programmatically.

We're interested in hearing from you! If you have questions about using the API, want to discuss a specific use case, or anything else, please contact us on Discord.

Terms of Use

To ensure fair use and maintain the quality of our service, we ask that all API users adhere to the following guidelines:

Respect rate limits: Please do not exceed the specified request limits for each endpoint. If you need higher limits, contact us to discuss options.
Use data responsibly: The recommendations and data provided by the API are intended for personal and non-commercial use. If you wish to use the data for commercial purposes, please reach out to us.
Provide attribution: If you use Recommander's API in your project, we ask that you provide appropriate attribution to Recommander as the source of the recommendations.
Do not scrape: Please do not scrape our website for data. Use the API endpoints provided for accessing information.
Contact us with questions: If you're unsure about any aspect of using the API or want to discuss a specific use case, don't hesitate to contact us.

Rate Limits

To ensure a stable and responsive experience for all users, the Recommander API enforces rate limits on incoming requests. The specific limits may vary by endpoint and user type, but generally, we allow a certain number of requests per minute or hour. If you exceed these limits, you will receive a 429 Too Many Requests response, and we ask that you wait before making additional requests. If you require higher limits for your project, please contact us to discuss your needs.

Data Sources

The Recommander API works on a data set derived from publicly available Commander decklists, primarily sourced from popular deck-building websites. We aggregate and analyze this data to generate card recommendations based on real-world deck-building trends and synergies. The API provides access to these recommendations, but does not expose the underlying decklist data directly.

We are committed to respecting the terms of service of the sites we source from and do not provide endpoints for scraping or bulk data access. Instead, we focus on delivering actionable insights through our recommendation endpoints while maintaining compliance with data usage policies.

At the request of our data sources, the API may serve a model that is trained on a subset of the available data, or that has certain limitations compared to our internal models.

API Specification

The recommendations API receives POST requests at /api/decks/recommend/top with a JSON body containing the commander, optional partner, and current deck contents. The response includes a list of recommended cards with their names, Scryfall Oracle IDs, and recommendation scores. All responses are wrapped in a standard envelope that indicates success or failure and includes error messages when applicable.

Data Types

`RecommendQuery`

The request payload for the recommendations endpoint.

Field	Type	Required	Nullable	Notes
`card_format`	enum	No	No	Card identifier format: `oracle_id`, `scryfall_id`, or `name`. Defaults to `oracle_id`.
`commander`	string	Yes	No	The main commander identifier.
`partner`	string	No	Yes	Optional partner commander.
`deck`	string[]	No	No	Cards encoded using the selected `card_format`.

`CardRecommendation`

A recommendation entry in the response.

Field	Type	Required	Nullable	Notes
`oracle_id`	uuid	Yes	No	UUID for the recommended card.
`name`	string	Yes	No	Human-readable card name.
`score`	double	Yes	No	Recommendation score used to rank results.

`ApiResult<RecommendResult>`

The standard response envelope wrapping the list of recommendations.

Field	Type	Required	Nullable	Notes
`result_code`	enum	Yes	No	Shared status enum describing success or failure.
`data`	CardRecommendation[]	No	Yes	Contains `recommendations` on success.
`error`	object	No	Yes	Contains a `messages` array on failure.

`ApiResultCode`

Possible values returned in result_code.

success
error_unknown
error_not_found
error_invalid_deck
error_invalid_cards
error_invalid_backend
error_backend_downstream
error_rate_limited
error_booting
error_model_loading

Methods

POST /api/decks/recommend/top

Accepts a deck query and returns a list of recommendations. The response is wrapped in the standard API result envelope.

Base URL https://api.recommander.cards/public-release

Operation RecommendPost

Response ApiResult<RecommendResult>

Request Body

Example

{
  "card_format": "name",
  "commander": "Gabriel Angelfire",
  "partner": null,
  "deck": [
    "Arbor Elf",
    "Beast Within",
    "Cultivate",
    "Danitha Capashen, Paragon",
    "Eidolon of Blossoms",
    "Heliod's Pilgrim",
    "Jukai Naturalist",
    "Kor Spiritdancer",
    "Mesa Enchantress",
    "Sanctum Weaver",
    "Sythis, Harvest's Hand",
    "Utopia Sprawl"
  ]
}

Response

Success Example

{
  "result_code": "success",
  "data": {
    "recommendations": [
      {
        "oracle_id": "795b096a-2bce-4588-a2c9-abc5ea40dc0c",
        "name": "Enchantress's Presence",
        "score": 0.9998
      },
      {
        "oracle_id": "dcb7e046-f01b-497c-88e5-57794eb30ce5",
        "name": "Canopy Vista",
        "score": 0.9998
      },
      {
        "oracle_id": "c8b143ad-43ec-4e0d-a440-e348daa31391",
        "name": "Swiftfoot Boots",
        "score": 0.9997
      },
      {
        "oracle_id": "e521322b-0e83-458c-8936-7021a80ee279",
        "name": "Temple of Plenty",
        "score": 0.9997
      },
      {
        "oracle_id": "24882fa2-3fe9-4c1b-aa3d-0e6488b9db27",
        "name": "Heroic Intervention",
        "score": 0.9994
      },
      {
        "oracle_id": "48a99dce-0aa9-4aac-81df-cec5f94c639d",
        "name": "Archon of Sun's Grace",
        "score": 0.9991
      }
    ]
  },
  "error": null
}

cURL

Example request against the public-release API:

curl -X POST https://api.recommander.cards/public-release/api/decks/recommend/top \
  -H "Content-Type: application/json" \
  -d '{
  "card_format": "name",
  "commander": "Gabriel Angelfire",
  "partner": null,
  "deck": [
    "Arbor Elf",
    "Beast Within",
    "Cultivate",
    "Danitha Capashen, Paragon",
    "Eidolon of Blossoms",
    "Heliod'\''s Pilgrim",
    "Jukai Naturalist",
    "Kor Spiritdancer",
    "Mesa Enchantress",
    "Sanctum Weaver",
    "Sythis, Harvest'\''s Hand",
    "Utopia Sprawl"
  ]
}'

Notes

Note that only cards with a score above 0.7 are included in the recommendations. If you do not receive any recommendations, it may be because the model did not find any cards that met that threshold for your query. You can experiment with different commanders, partners, and deck contents to see how the recommendations change.