API Documentation

This page outlines all the different API calls available

---

Submit Run

Sends a run request to TAG. The game and chosen parameters must be provided, as well as a valid API Key. If sucesfull, a run ID will be returned which can be used to retrieve the results of the run after completion.

Run Type

Each run has a type, which determines how many matchups are played:

• fast: 36 matchups
• medium: 360 matchups
• full: 3600 matchups

Request

• URL: balance-competition.tabletopgames.ai/api/submit_run
• Method: POST
• Headers: All Required
  • Content-Type: application/json
• Body: JSON (All required)
  • game: String - The game to be played, valid strings are: Dominion, ExplodingKittens, Wonders7, CantStop
  • params: JSON[String, String] - A map containg parameters and their chosen values
  • api_key: String - A valid API key
  • run_type: String - Which type of run this is

Response

• Status:
  • 200 OK: Request completed sucesfully
  • 400 Bad Request: There was an issue with one of the provided parameters
  • 401 Unauthrorized: An invalid API key was provided
• Body JSON
  • error: (400 / 401) String - Describes why the request couldn’t be completed
  • runID: (200 Only) Number - The ID of the created run

Example

Request

curl -i -X POST http://balance-competition.tabletopgames.ai/api/submit_run 
    -H "Content-Type: application/json" 
    -d '{"game": "Dominion", "params": {"HAND_SIZE": 3}, "api_key": "7079cc2c-2ced-4031-ba9a-6eac68945c22", "run_type":"fast"}'

Response

HTTP/1.1 200 OK
access-control-allow-origin: *
content-length: 12
content-type: application/json
Date: Thu, 17 Apr 2025 13:58:12 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"runID":13}

---

Query Run

A request to retrieve the status of a run. The status can be:

• created: The run has been created and is in the queue
• running: The run is currently being processed in TAG
• results: TAG has finished running, and results are being calculated
• error: There was a fatal error and the run could not complete
• complete: Results have been calculated and can be retrieved

Request

• URL: balance-competition.tabletopgames.ai/api/query_run
• Method: GET
• Params: (all required)
  • id: Number - The ID of the run to query

Response

• Status:
  • 200 OK: Request completed sucesfully
  • 400 Bad Request: There ID was not provided or was not a number
  • 404 Not Found: No run with the provided ID was found
• Body JSON
  • error: (400 / 404) String - Describes why the request couldn’t be completed
  • status: (200 Only) String - The run’s status

Example

Request

curl -i -X GET http://balance-competition.tabletopgames.ai/api/query_run?id=13

Response

HTTP/1.1 200 OK
access-control-allow-origin: *
content-length: 25
content-type: application/json
Date: Thu, 17 Apr 2025 14:15:12 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"run_status":"complete"}

---

Retrive Results

Allows you to retrieve the result of a run, this represents how balanced the game was. The higher this score the better.

Request

• URL: balance-competition.tabletopgames.ai/api/retrieve_result
• Method: GET
• Params: (all required)
  • id: Number - The ID of the run to retrieve
  • api_key String - A valid API key

Response

• Status:
  • 200 OK: Request completed sucesfully
  • 400 Bad Request: There was an issue with one of the provided params
  • 404 Not Found: The run was not found, or the results are not yet ready
• Body JSON
  • error: (400 / 404) String - Describes why the request couldn’t be completed
  • score: (200 Only) Number - The score of the run (how balanced the game was)

Example

Request

curl -i -X GET http://balance-competition.tabletopgames.ai/api/retrieve_result?id=13&api_key=7079cc2c-2ced-4031-ba9a-6eac68945c22

Response

HTTP/1.1 200 OK
access-control-allow-origin: *
content-length: 49
content-type: application/json
Date: Thu, 17 Apr 2025 14:24:58 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"score":85}        

---