The 2025 Tabletop Games Balancing Competition

Home Getting Started Documentation Games Discord

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.

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
    • params: JSON[String, String] - A map containg parameters and their chosen values
    • 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 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"}'

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}

Leaderboard