Skip to content

Commit 2b9a066

Browse files
lexicalunitlexicalunit
committed
Adds docs for API
1 parent a60ff45 commit 2b9a066

File tree

2 files changed

+199
-6
lines changed

2 files changed

+199
-6
lines changed

‎API.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# SpellBot API
2+
3+
SpellBot has a public API that can be used to access game and user data. As well as a few authenticated endpoints that can be used to manage game and user data.
4+
5+
**Base URL:** `https://prod.app.spellbot.io/`
6+
7+
## Public Endpoints
8+
9+
### GET `/`
10+
11+
Returns a 200 response with the text "ok" in the body.
12+
13+
### GET `/g/{guild}/c/{channel}`
14+
15+
Returns a HTML page with a list of games played in the given channel.
16+
17+
### GET `/g/{guild}/u/{user}`
18+
19+
Returns a HTML page with a list of games played by the given user.
20+
21+
## Authenticated Endpoints
22+
23+
All authenticated endpoints require a valid API token to be passed in the `Authorization` header. The token should be prefixed with `"Bearer "`.
24+
25+
If there is an error processing these requests, the response will follow the following format:
26+
27+
```json
28+
{
29+
"error": "Something went wrong"
30+
}
31+
```
32+
33+
### POST `/api/game/{game}/verify`
34+
35+
Verifies the user's PIN for the given game for the given guild. This API is for external applications that track a user's game history, such as [Mythic Track](https://www.mythictrack.com/).
36+
37+
#### Request
38+
39+
```json
40+
{
41+
"user_xid": 1234567890,
42+
"guild_xid": 1234567890,
43+
"pin": "123456"
44+
}
45+
```
46+
47+
#### Response
48+
49+
```json
50+
{
51+
"result": {
52+
"verified": true
53+
}
54+
}
55+
```
56+
57+
### POST `/api/game/{game}/record`
58+
59+
Records the given game as played by the given users and their commanders. This will send a DM to each user with the game record, informing them that the game was recorded. This API is for external applications that track a user's game history, such as [Mythic Track](https://www.mythictrack.com/).
60+
61+
#### Request
62+
63+
```json
64+
{
65+
"players": [
66+
{
67+
"xid": 1234567890,
68+
"commander": "Urza, Lord High Artificer"
69+
},
70+
{
71+
"xid": 1234567890,
72+
"commander": "Najeela, the Blade Blossom"
73+
}
74+
],
75+
"winner": 1234567890,
76+
"tracker": 1234567890
77+
}
78+
```
79+
80+
#### Response
81+
82+
```json
83+
{
84+
"result": {
85+
"success": true
86+
}
87+
}
88+
```
89+
90+
### POST `/api/notification`
91+
92+
This API is for external applications that want to create a notification in Discord for a game that was created outside of Discord. For example, a user might create a game on [Convoke](https://www.convoke.games/) and want to notify their friends in Discord that the game is ready to play.
93+
94+
#### Request
95+
96+
```json
97+
{
98+
"link": "https://www.convoke.games/game/1234567890",
99+
"guild": 1234567890,
100+
"channel": 1234567890,
101+
"players": ["Alice", "Bob"],
102+
"format": 1,
103+
"bracket": 1,
104+
"service": 1
105+
}
106+
```
107+
108+
**Brackets:**
109+
110+
| Value | Description |
111+
| --- | --- |
112+
| 1 | None |
113+
| 2 | Bracket 1: Exhibition |
114+
| 3 | Bracket 2: Core |
115+
| 4 | Bracket 3: Upgraded |
116+
| 5 | Bracket 4: Optimized |
117+
| 6 | Bracket 5: Competitive |
118+
119+
**Formats:**
120+
121+
| Value | Description |
122+
| --- | --- |
123+
| 1 | Commander |
124+
| 2 | Standard |
125+
| 3 | Sealed |
126+
| 4 | Modern |
127+
| 5 | Vintage |
128+
| 6 | Legacy |
129+
| 7 | Brawl (Two Players) |
130+
| 8 | Brawl (Multiplayer) |
131+
| 9 | Two Headed Giant |
132+
| 10 | Pauper |
133+
| 11 | Pioneer |
134+
| 12 | EDH Max |
135+
| 13 | EDH High |
136+
| 14 | EDH Mid |
137+
| 15 | EDH Low |
138+
| 16 | EDH Battlecruiser |
139+
| 17 | Planechase |
140+
| 18 | Commander Precons |
141+
| 19 | Oathbreaker |
142+
| 20 | Duel Commander |
143+
| 21 | cEDH |
144+
| 22 | Archenemy |
145+
| 23 | Pauper EDH |
146+
147+
**Services:**
148+
149+
| Value | Description |
150+
| --- | --- |
151+
| 1 | Not any |
152+
| 2 | SpellTable |
153+
| 3 | Cockatrice |
154+
| 4 | XMage |
155+
| 5 | MTG Arena |
156+
| 6 | MTG Online |
157+
| 7 | TabletopSim |
158+
| 8 | Table Stream |
159+
| 9 | Convoke |
160+
161+
#### Response
162+
163+
```json
164+
{
165+
"result": {
166+
"success": true,
167+
"id": 1234567890
168+
}
169+
}
170+
```
171+
172+
### PATCH `/api/notification/{notif}`
173+
174+
This is for updating notifications created with `POST /api/notification`. You can update the list of players and/or mark the game as started.
175+
176+
#### Request
177+
178+
```json
179+
{
180+
"players": ["Alice", "Bob"],
181+
"started_at": "2025-12-05T12:00:00Z"
182+
}
183+
```
184+
185+
#### Response
186+
187+
```json
188+
{
189+
"result": {
190+
"success": true
191+
}
192+
}
193+
```

‎scripts/enums.py‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,14 @@
33

44
from spellbot.enums import GameBracket, GameFormat, GameService
55

6-
print("brackets:") # noqa: T201
6+
print("# Brackets\n| Value | Description |\n| --- | --- |") # noqa: T201
77
for bracket in GameBracket:
8-
print(f"{bracket.value}: {bracket}") # noqa: T201
8+
print(f"| {bracket.value} | {bracket} |") # noqa: T201
99

10-
print("\nformats:") # noqa: T201
10+
print("\n# Formats\n| Value | Description |\n| --- | --- |") # noqa: T201
1111
for format in GameFormat:
12-
print(f"{format.value}: {format}") # noqa: T201
12+
print(f"| {format.value} | {format} |") # noqa: T201
1313

14-
print("\nservices:") # noqa: T201
14+
print("\n# Services\n| Value | Description |\n| --- | --- |") # noqa: T201
1515
for service in GameService:
16-
print(f"{service.value}: {service}") # noqa: T201
16+
print(f"| {service.value} | {service} |") # noqa: T201

0 commit comments

Comments
 (0)