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",
"levels_completed": 0,
"win_levels": 254,
"action_input": {
"id": 0,
"data": {}
},
"available_actions": [
1,
2,
3,
4
]
}Start or reset game instance
Creates a new game session or resets an existing one,
depending on the presence of guid in the request body:
• Omit guid or set it to null → start a brand-new game
instance.
• Provide an existing guid → reset that session.
- If at least one ACTION command has been issued since the last level transition, only the current level is restarted.
- If no ACTIONs have been issued, the entire game resets.
Two consecutive RESETs therefore guarantee a completely fresh game.
The call always returns the first (or refreshed) frame of the game state, along with updated score and win condition.
Note: The response includes cookies (particularly AWSALB* cookies) that must be included in all subsequent ACTION commands for this session. These cookies ensure requests are routed to the same backend instance maintaining your game state.
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",
"levels_completed": 0,
"win_levels": 254,
"action_input": {
"id": 0,
"data": {}
},
"available_actions": [
1,
2,
3,
4
]
}Authorizations
Body
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.
Identifier of the game to start or reset (e.g. ls20).
scorecard identifier returned by OpenScorecardResponse. Required to attribute this play to the correct scorecard.
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 progress, the
current game state, and an echo of the triggering action.
Game identifier for the running session.
Server-generated session ID; use this for all subsequent commands.
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.
0 <= x <= 15Current state of the session:
• NOT_FINISHED - game in progress, not yet WIN or GAME_OVER.
• NOT_PLAYED - no game has been started.
• WIN - session ended in victory.
• GAME_OVER - session ended in defeat.
NOT_PLAYED, NOT_FINISHED, WIN, GAME_OVER Current cumulative number of levels completed for this run.
0 <= x <= 254Level threshold required to reach the WIN state. Mirrors the game's configured win condition so agents can adapt dynamically without hard-coding values.
0 <= x <= 254Echo of the command that produced this frame.
Show child attributes
Show child attributes
List of available actions for the current game.
0, 1, 2, 3, 4, 5, 6, 7 Whether the RESET created a new game rather than resetting the current level.
Was this page helpful?