---
title: "Start or reset game instance"
method: POST
path: "/api/cmd/RESET"
tags: ["Commands"]
---

# Start or reset game instance

`POST /api/cmd/RESET`

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.

## Request body

- ResetCommand — 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, nullable — 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 `200`

First frame after starting or resetting the session.

- FrameResponse — 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` array[], 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.
    - array[]
      - integer[]
  - `state` 'NOT_FINISHED' | 'NOT_STARTED' | 'WIN' | 'GAME_OVER', 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.
  - `levels_completed` integer, required — Current cumulative number of levels completed for this run.
  - `win_levels` integer, required — Level threshold required to reach the **WIN** state. Mirrors the game's configured win condition so agents can adapt dynamically without hard-coding values.
  - `action_input` object, required — Echo of the command that produced this frame.
    - `id` integer — Client-assigned or sequential action index.
    - `data` object — Additional parameters originally sent with the action.
  - `available_actions` integer[], required — List of available actions for the current game.

## Other responses

- `400` — Bad request - possible causes: • Unknown `game_id` • Missing or unknown `card_id` • `guid` does not correspond to an active session
- `401` — Missing or invalid **X-API-Key** header.

---

[API](https://skmtc.net/arcprize/apis/arc-agi-3-rest-api.md) · [All operations](https://skmtc.net/arcprize/apis/arc-agi-3-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arcprize/arc-agi-3-rest-api/versions/195a67c94d38/schema)