> ## Documentation Index > Fetch the complete documentation index at: https://docs.arcprize.org/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /arc3v1.yaml post /api/cmd/RESET openapi: 3.0.3 info: title: ARC‑AGI‑3 REST API version: 1.0.0 description: > Programmatic interface for running agents against ARC‑AGI‑3 games, opening/closing score‑cards and driving game state with actions. All requests **require** an `X‑API‑Key` header issued from the ARC‑AGI‑3 web console. **Important: Session Affinity via Cookies** Games are stateful and require session affinity. The server sets cookies (especially `AWSALB*` cookies) in responses that **must be included in all subsequent requests** for the same game session. These cookies route requests to the correct backend instance maintaining your game state. Most HTTP clients handle cookies automatically, but ensure your client preserves and sends cookies received from RESET and ACTION responses. servers: - url: https://three.arcprize.org security: [] tags: - name: Games - name: Scorecards - name: Commands paths: /api/cmd/RESET: post: tags: - Commands summary: Start or reset game instance description: > 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. operationId: resetGame requestBody: description: Game identifier, scorecard ID, and (optionally) the session `guid`. required: true content: application/json: schema: $ref: '#/components/schemas/ResetCommand' examples: newGame: summary: Start a new session value: game_id: ls20-016295f7601e card_id: 8bb3b1b8-4b46-4a29-a13b-ad7850a0f916 levelReset: summary: Reset current level of an existing session value: game_id: ls20-016295f7601e card_id: 8bb3b1b8-4b46-4a29-a13b-ad7850a0f916 guid: 2fa5332c-2e55-4825-b5c5-df960d504470 responses: '200': description: First frame after starting or resetting the session. content: application/json: schema: $ref: '#/components/schemas/FrameResponse' examples: frame: value: 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 '400': description: | Bad request - possible causes: • Unknown `game_id` • Missing or unknown `card_id` • `guid` does not correspond to an active session '401': description: Missing or invalid **X-API-Key** header. security: - ApiKeyAuth: [] components: schemas: ResetCommand: type: object description: | 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. properties: game_id: type: string description: Identifier of the game to start or reset (e.g. `ls20`). card_id: type: string description: | scorecard identifier returned by **OpenScorecardResponse**. Required to attribute this play to the correct scorecard. guid: type: string nullable: true description: | 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. required: - game_id - card_id FrameResponse: type: object description: | 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. properties: game_id: type: string description: Game identifier for the running session. guid: type: string description: Server-generated session ID; use this for all subsequent commands. frame: type: array description: | 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. items: type: array items: type: array items: type: integer minimum: 0 maximum: 15 state: type: string description: > 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. enum: - NOT_FINISHED - NOT_STARTED - WIN - GAME_OVER levels_completed: type: integer description: Current cumulative number of levels completed for this run. minimum: 0 maximum: 254 win_levels: type: integer description: | Level threshold required to reach the **WIN** state. Mirrors the game's configured win condition so agents can adapt dynamically without hard-coding values. minimum: 0 maximum: 254 action_input: type: object description: Echo of the command that produced this frame. properties: id: type: integer description: Client-assigned or sequential action index. data: type: object description: Additional parameters originally sent with the action. additionalProperties: true available_actions: type: array description: List of available actions for the current game. items: type: integer enum: - 1 - 2 - 3 - 4 - 5 - 6 required: - game_id - guid - frame - state - levels_completed - win_levels - action_input - available_actions securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key ````