POST
/
api
/
cmd
/
ACTION1
Execute simple action 1
curl --request POST \
  --url https://three.arcprize.org/api/cmd/ACTION1 \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "game_id": "ls20-016295f7601e",
  "guid": "2fa5332c-2e55-4825-b5c5-df960d504470",
  "reasoning": {
    "policy": "π_left"
  }
}'
{
  "game_id": "ls20-016295f7601e",
  "guid": "2fa5332c-2e55-4825-b5c5-df960d504470",
  "frame": [
    [
      [
        0,
        0,
        1,
        "…"
      ],
      [
        "…"
      ]
    ]
  ],
  "state": "NOT_FINISHED",
  "score": 3,
  "win_score": 254,
  "action_input": {
    "id": 1
  },
  "available_actions": [
    1,
    2,
    3,
    4
  ]
}

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Game/session identifiers plus optional reasoning data.

Issues a one-parameter action (ACTION1 - ACTION5) to a running game instance identified by guid.

​
game_id
string
required

Game identifier this action targets.

​
guid
string
required

Server-generated session ID obtained from a RESET response.

​
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.