POST
/
api
/
cmd
/
RESET
curl --request POST \
  --url https://three.arcprize.org/api/cmd/RESET \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "game_id": "ls20-016295f7601e",
  "card_id": "8bb3b1b8-4b46-4a29-a13b-ad7850a0f916"
}'
{
  "game_id": "ls20-016295f7601e",
  "guid": "2fa5332c-2e55-4825-b5c5-df960d504470",
  "frame": [
    [
      [
        0,
        0,
        0,
        "…"
      ],
      [
        "…"
      ]
    ]
  ],
  "state": "NOT_FINISHED",
  "score": 0,
  "win_score": 254,
  "action_input": {
    "id": 0,
    "data": {}
  },
  "available_actions": [
    1,
    2,
    3,
    4
  ]
}

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Game identifier, scorecard ID, and (optionally) the session guid.

Starts a new game session or resets an existing one, depending on whether a guid is supplied.

• No guid (null/empty) → A brand-new game instance is created and the response will include its freshly minted guid.

• With guid → The server issues a reset to that specific instance: - If at least one ACTION command has been executed in the current level, only that level is reset (typical “try again” behaviour). - If no ACTION commands have been executed since the last level transition, the entire game is reset to its initial state.

Sending two RESET commands back-to-back therefore always yields a completely fresh game.

All plays should be associated with an open scorecard via card_id so aggregated results can be tracked.

​
game_id
string
required

Identifier of the game to start or reset (e.g. ls20).

​
card_id
string
required

scorecard identifier returned by OpenScorecardResponse. Required to attribute this play to the correct scorecard.

​
guid
string | null

Server-generated game session ID.
• Omit or set to null to create a new game.
• Provide an existing value to reset that game as described above.

Response

First frame after starting or resetting the session.

Snapshot returned after every RESET or ACTION command.
Includes the latest visual frame(s), cumulative score details, the current game state, and an echo of the triggering action.

​
game_id
string
required

Game identifier for the running session.

​
guid
string
required

Server-generated session ID; use this for all subsequent commands.

​
frame
integer[][][]
required

One or more consecutive visual frames. Each frame is a 64 × 64 grid of 4-bit colour indices (integers 0-15). Multiple frames may be returned if the environment advances internally (e.g., animations) before settling.

​
state
enum<string>
required

Current state of the session:

• NOT_FINISHED - game in progress, not yet WIN or GAME_OVER.
• NOT_STARTED - session has ended (WIN or GAME_OVER) and requires RESET.
• WIN - session ended in victory.
• GAME_OVER - session ended in defeat.

Available options:
NOT_FINISHED,
NOT_STARTED,
WIN,
GAME_OVER
​
score
integer
required

Current cumulative score for this run.

Required range: 0 <= x <= 254
​
win_score
integer
required

Score threshold required to reach the WIN state. Mirrors the game's configured win condition so agents can adapt dynamically without hard-coding values.

Required range: 0 <= x <= 254
​
action_input
object
required

Echo of the command that produced this frame.

​
available_actions
enum<integer>[]
required

List of available actions for the current game.