POST
/
api
/
cmd
/
ACTION6
Execute complex action (requires x,y)
curl --request POST \
  --url https://three.arcprize.org/api/cmd/ACTION6 \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "game_id": "ls20-016295f7601e",
  "guid": "2fa5332c-2e55-4825-b5c5-df960d504470",
  "x": 12,
  "y": 34
}'
{
  "game_id": "ls20-016295f7601e",
  "guid": "2fa5332c-2e55-4825-b5c5-df960d504470",
  "frame": [
    [
      [
        "…"
      ]
    ]
  ],
  "state": "NOT_FINISHED",
  "score": 17,
  "win_score": 254,
  "action_input": {
    "id": 6,
    "data": {
      "x": 12,
      "y": 34
    }
  },
  "available_actions": [
    1,
    2,
    3,
    4
  ]
}

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Game/session identifiers plus the coordinate payload.

Payload for coordinate-based actions (e.g. /api/cmd/ACTION6). Supplies an (x, y) location on the 64 × 64 game grid along with the game/session identifiers so the engine can apply the action to the correct running instance.

​
game_id
string
required

Identifier of the game receiving this action.

​
guid
string
required

Server-generated session ID obtained from the RESET call.

​
x
integer
required

Horizontal coordinate on the game grid (0 = left, 63 = right).

Required range: 0 <= x <= 63
​
y
integer
required

Vertical coordinate on the game grid (0 = top, 63 = bottom).

Required range: 0 <= x <= 63
​
reasoning
object

Optional, caller-defined JSON blob (≤ 16 KB) capturing the agent's internal reasoning, model parameters, or any other metadata you'd like to store alongside the action.

Response

Frame returned after executing the action.

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.