RulesGuru API
The RulesGuru API provides a way for developers to access rules questions programmatically. Requests should be submitted to /api/questions/ as a GET request with parameter "json=[settings]", where "[settings]" is percent-encoded JSON. The properties of the JSON object are explained in the table below. Any omitted properties will be assumed to be the default in the right column.
Property
Data Type
Description
Default Value
count
Number
The number of questions you want.
1
level
Array of strings (order-agnostic)
Length 1 to 5, contains any combination of acceptable levels. Options are "0", "1", "2", "3", and "Corner Case".
["0", "1", "2"]
complexity
Array of strings (order-agnostic)
Length 1 to 3, contains any combination acceptable complexities. Options are "Simple", "Intermediate", and "Complicated".
["Simple", "Intermediate"]
legality
String
Can be "Standard", "Pioneer", "Modern", "All of Magic", or "Choose Expansions".
"Modern"
expansions
Array of strings (order-agnostic)
Only used if legality is "Choose Expansions". Refer to the dropdown menu in the sidebar on the home page for a list of all available expansions.
[]
playableOnly
Boolean
If true, questions will be limited to cards that see tournament play in the given format. Ignored if legality is "All of Magic" or "Choose Expansions".
false
tags
Array of strings (order-agnostic)
A list of tags. Refer to the dropdown menu in the sidebar on the home page for a list of all available tags.
["Unsupported answers"]
rules
Array of strings (order-agnostic)
A list of rules. Refer to the dropdown menu in the sidebar on the home page for a list of all available rules. Or, you know, the CR.
[]
cards
Array of strings (order-agnostic)
A list of cards. Refer to the dropdown menu in the sidebar on the home page for a list of all available cards. Or, you know, Scryfall.
[]
tagsConjunc
String
The logical conjunction to be used upon the list of tags. Can be "AND", "OR", or "NOT".
"NOT"
rulesConjunc
String
The logical conjunction to be used upon the list of rules. Can be "AND", "OR", or "NOT".
"OR"
cardsConjunc
String
The logical conjunction to be used upon the list of cards. Can be "AND", "OR", or "NOT".
"OR"
previousId
Number
If this is specified, the returned questions will not be random. Instead they'll be the next X questions that match the given settings that come after the given id. (Wrapping back around to 1 one the end is reached.)
undefined
id
Number
The ID of a specific question you want to return. If this property is specified, only that question is returned, and most other fields are ignored. Legality, expansions, playableOnly, cards, and cardsConjunc will still be followed if possible. If any of those fields are left undefined, the defaults will be set to the most permissive option rather than the ones listed in this table.
undefined
Here is an example JSON string:
{
"count": 1,
"level": ["0", "1", "2"],
"complexity": ["Simple", "Intermediate"],
"legality": "Modern",
"expansions": [],
"playableOnly": false,
"tags": ["Unsupported answers"],
"tagsConjunc": "NOT",
"rules": [],
"rulesConjunc": "OR",
"cards": [],
"cardsConjunc": "OR"
}
After minifying and percent-encoding it, here is the resulting query:
https://rulesguru.net/api/questions/?json=%7B%22count%22%3A1%2C%22level%22%3A%5B%220%22%2C%221%22%2C%222%22%5D%2C%22complexity%22%3A%5B%22Simple%22%2C%22Intermediate%22%5D%2C%22legality%22%3A%22Modern%22%2C%22expansions%22%3A%5B%5D%2C%22playableOnly%22%3Afalse%2C%22tags%22%3A%5B%22Unsupported+answers%22%5D%2C%22tagsConjunc%22%3A%22NOT%22%2C%22rules%22%3A%5B%5D%2C%22rulesConjunc%22%3A%22OR%22%2C%22cards%22%3A%5B%5D%2C%22cardsConjunc%22%3A%22OR%22%7D
The return value is a JSON array of objects each representing a question. Each question object has the following properties:
Property
Data Type
Description
id
Number
The ID of the question.
level
String
The level of the question.
complexity
String
The complexity of the question.
tags
Array of strings
The tags that the question has.
questionSimple
String
The text of the question, human-readable.
questionHTML
String
The text of the question, in HTML.
answerSimple
String
The answer to the question, human-readable, with rule citations removed.
answerSimpleCited
String
The answer to the question, human-readable, including rule citations.
answerHTML
String
The answer to the question, in HTML.
submitterName
String
The person who submitted the question, or the empty string if no name was given.
includedCards
Array of objects
A list of cards mentioned in the question or answer, in the order mentioned. Object formatting is from MTGJSON, with the errors fixed and a few properties added, removed, or tweaked. For a full list of the differences, you can see the code here.
citedRules
Array of objects
A list of rules mentioned in the question or answer, in the order mentioned. Object formatting is from the Academy Ruins API.
url
string
A link to the question on RulesGuru.
Finding questions that match the given parameters is computationally expensive, so requests are rate-limited to one every 2 seconds. If you need multiple questions of the same settings, submit a single request with the appropriate "count" variable rather than submitting that many individual requests.
This API is a work in progress, meaning features and syntax may change. If you have any feature requests or bug reports, please let us know via our or on Github.