Arc Prize Foundation Commands API
The Commands API from Arc Prize Foundation — 8 operation(s) for commands.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/arc-prize-foundation-commands-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: ARC‑AGI‑3 REST Commands 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.
servers:
- url: https://three.arcprize.org
tags:
- 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
security:
- ApiKeyAuth: []
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: \n• Unknown `game_id` \n• Missing or unknown `card_id` \n• `guid` does not correspond to an active session\n"
'401':
description: Missing or invalid **X-API-Key** header.
/api/cmd/ACTION1:
post:
tags:
- Commands
summary: Execute simple action 1
description: 'Issues **ACTION 1** to the specified game session.
This is a single-parameter command (no X/Y coordinates): the exact
in-game effect depends on the title—for example, it might
represent “move up” or “select option A”.
The request must include:
• `game_id` — which game to act on
• `guid` — the active session identifier returned from RESET
An optional `reasoning` JSON blob (≤ 16 KB) can be attached for
audit or research purposes.
A successful call returns the next visual frame(s) and updated
score/state.'
operationId: action1
security:
- ApiKeyAuth: []
requestBody:
description: Game/session identifiers plus optional reasoning data.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleActionCommand'
examples:
action:
value:
game_id: ls20-016295f7601e
guid: 2fa5332c-2e55-4825-b5c5-df960d504470
reasoning:
policy: π_left
responses:
'200':
description: Frame returned after executing the action.
content:
application/json:
schema:
$ref: '#/components/schemas/FrameResponse'
examples:
frame:
value:
game_id: ls20-016295f7601e
guid: 2fa5332c-2e55-4825-b5c5-df960d504470
frame:
- - - 0
- 0
- 1
- …
- - …
state: NOT_FINISHED
levels_completed: 3
win_levels: 254
action_input:
id: 1
available_actions:
- 1
- 2
- 3
- 4
'400':
description: "Bad request - possible causes: \n• Unknown `game_id` or invalid format \n• `guid` not found or does not belong to `game_id` \n• `reasoning` field exceeds 16 KB or is malformed\n"
'401':
description: Missing or invalid **X-API-Key** header.
/api/cmd/ACTION2:
post:
tags:
- Commands
summary: Execute simple action 2
description: 'Issues **ACTION 2** to the specified game session.
This is a single-parameter command (no X/Y coordinates): the exact
in-game effect depends on the title—for example, it might
represent “move down" or “select option B”.
The request must include:
• `game_id` — which game to act on
• `guid` — the active session identifier returned from RESET
An optional `reasoning` JSON blob (≤ 16 KB) can be attached for
audit or research purposes.
A successful call returns the next visual frame(s) and updated
score/state.'
operationId: action2
security:
- ApiKeyAuth: []
requestBody:
description: Game/session identifiers plus optional reasoning data.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleActionCommand'
examples:
action:
value:
game_id: ls20-016295f7601e
guid: 2fa5332c-2e55-4825-b5c5-df960d504470
reasoning:
policy: π_left
responses:
'200':
description: Frame returned after executing the action.
content:
application/json:
schema:
$ref: '#/components/schemas/FrameResponse'
examples:
frame:
value:
game_id: ls20-016295f7601e
guid: 2fa5332c-2e55-4825-b5c5-df960d504470
frame:
- - - 0
- 0
- 1
- …
- - …
state: NOT_FINISHED
levels_completed: 3
win_levels: 254
action_input:
id: 2
available_actions:
- 1
- 2
- 3
- 4
'400':
description: "Bad request - possible causes: \n• Unknown `game_id` or invalid format \n• `guid` not found or does not belong to `game_id` \n• `reasoning` field exceeds 16 KB or is malformed\n"
'401':
description: Missing or invalid **X-API-Key** header.
/api/cmd/ACTION3:
post:
tags:
- Commands
summary: Execute simple action 3
description: 'Issues **ACTION 3** to the specified game session.
This is a single-parameter command (no X/Y coordinates): the exact
in-game effect depends on the title—for example, it might
represent “move left” or “select option C”.
The request must include:
• `game_id` — which game to act on
• `guid` — the active session identifier returned from RESET
An optional `reasoning` JSON blob (≤ 16 KB) can be attached for
audit or research purposes.
A successful call returns the next visual frame(s) and updated
score/state.'
operationId: action3
security:
- ApiKeyAuth: []
requestBody:
description: Game/session identifiers plus optional reasoning data.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleActionCommand'
examples:
action:
value:
game_id: ls20-016295f7601e
guid: 2fa5332c-2e55-4825-b5c5-df960d504470
reasoning:
policy: π_left
responses:
'200':
description: Frame returned after executing the action.
content:
application/json:
schema:
$ref: '#/components/schemas/FrameResponse'
examples:
frame:
value:
game_id: ls20-016295f7601e
guid: 2fa5332c-2e55-4825-b5c5-df960d504470
frame:
- - - 0
- 0
- 1
- …
- - …
state: NOT_FINISHED
levels_completed: 3
win_levels: 254
action_input:
id: 3
available_actions:
- 1
- 2
- 3
- 4
'400':
description: "Bad request - possible causes: \n• Unknown `game_id` or invalid format \n• `guid` not found or does not belong to `game_id` \n• `reasoning` field exceeds 16 KB or is malformed\n"
'401':
description: Missing or invalid **X-API-Key** header.
/api/cmd/ACTION4:
post:
tags:
- Commands
summary: Execute simple action 4
description: 'Issues **ACTION 4** to the specified game session.
This is a single-parameter command (no X/Y coordinates): the exact
in-game effect depends on the title—for example, it might
represent “move right" or “select option D”.
The request must include:
• `game_id` — which game to act on
• `guid` — the active session identifier returned from RESET
An optional `reasoning` JSON blob (≤ 16 KB) can be attached for
audit or research purposes.
A successful call returns the next visual frame(s) and updated
score/state.'
operationId: action4
security:
- ApiKeyAuth: []
requestBody:
description: Game/session identifiers plus optional reasoning data.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleActionCommand'
examples:
action:
value:
game_id: ls20-016295f7601e
guid: 2fa5332c-2e55-4825-b5c5-df960d504470
reasoning:
policy: π_left
responses:
'200':
description: Frame returned after executing the action.
content:
application/json:
schema:
$ref: '#/components/schemas/FrameResponse'
examples:
frame:
value:
game_id: ls20-016295f7601e
guid: 2fa5332c-2e55-4825-b5c5-df960d504470
frame:
- - - 0
- 0
- 1
- …
- - …
state: NOT_FINISHED
levels_completed: 3
win_levels: 254
action_input:
id: 4
available_actions:
- 1
- 2
- 3
- 4
'400':
description: "Bad request - possible causes: \n• Unknown `game_id` or invalid format \n• `guid` not found or does not belong to `game_id` \n• `reasoning` field exceeds 16 KB or is malformed\n"
'401':
description: Missing or invalid **X-API-Key** header.
/api/cmd/ACTION5:
post:
tags:
- Commands
summary: Execute simple action 5
description: 'Issues **ACTION 5** to the specified game session.
This is a single-parameter command (no X/Y coordinates): the exact
in-game effect depends on the title—for example, it might
represent “jump”, "rotate", "fire" or “select option E”.
The request must include:
• `game_id` — which game to act on
• `guid` — the active session identifier returned from RESET
An optional `reasoning` JSON blob (≤ 16 KB) can be attached for
audit or research purposes.
A successful call returns the next visual frame(s) and updated
score/state.'
operationId: action5
security:
- ApiKeyAuth: []
requestBody:
description: Game/session identifiers plus optional reasoning data.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleActionCommand'
examples:
action:
value:
game_id: ls20-016295f7601e
guid: 2fa5332c-2e55-4825-b5c5-df960d504470
reasoning:
policy: π_left
responses:
'200':
description: Frame returned after executing the action.
content:
application/json:
schema:
$ref: '#/components/schemas/FrameResponse'
examples:
frame:
value:
game_id: ls20-016295f7601e
guid: 2fa5332c-2e55-4825-b5c5-df960d504470
frame:
- - - 0
- 0
- 1
- …
- - …
state: NOT_FINISHED
levels_completed: 3
win_levels: 254
action_input:
id: 5
available_actions:
- 1
- 2
- 3
- 4
'400':
description: "Bad request - possible causes: \n• Unknown `game_id` or invalid format \n• `guid` not found or does not belong to `game_id` \n• `reasoning` field exceeds 16 KB or is malformed\n"
'401':
description: Missing or invalid **X-API-Key** header.
/api/cmd/ACTION6:
post:
tags:
- Commands
summary: Execute complex action (requires x,y)
description: 'Issues **ACTION 6**—a two-parameter command that supplies explicit
X/Y coordinates—to an active game session. Common use-cases
include “click/tap at (x,y)”, “place a tile”, or “shoot a
projectile,” depending on the game''s mechanics.
Required fields
• `game_id` — the game to act in
• `guid` — session identifier obtained from RESET
• `x`,`y` — zero-based grid coordinates (0-63 inclusive)
On success the server applies the action, advances game logic to
the next stable frame, and returns that frame together with the
updated score, state, and win condition.'
operationId: action6
security:
- ApiKeyAuth: []
requestBody:
description: Game/session identifiers plus the coordinate payload.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ComplexActionCommand'
examples:
placeTile:
summary: Place at (12, 34)
value:
game_id: ls20-016295f7601e
guid: 2fa5332c-2e55-4825-b5c5-df960d504470
x: 12
y: 34
responses:
'200':
description: Frame returned after executing the action.
content:
application/json:
schema:
$ref: '#/components/schemas/FrameResponse'
examples:
frame:
value:
game_id: ls20-016295f7601e
guid: 2fa5332c-2e55-4825-b5c5-df960d504470
frame:
- - - …
state: NOT_FINISHED
levels_completed: 17
win_levels: 254
action_input:
id: 6
data:
x: 12
y: 34
available_actions:
- 1
- 2
- 3
- 4
'400':
description: "Bad request - possible causes: \n• Unknown `game_id` \n• `guid` not found or does not belong to the supplied `game_id` \n• `x` or `y` outside the 0-63 range\n"
'401':
description: Missing or invalid **X-API-Key** header.
/api/cmd/ACTION7:
post:
tags:
- Commands
summary: Execute simple action 7
description: 'Issues **ACTION 7** to the specified game session.
This is a single-parameter command (no X/Y coordinates):
ACTION7 will always be an undo action for games that support it.
The request must include:
• `game_id` — which game to act on
• `guid` — the active session identifier returned from RESET
An optional `reasoning` JSON blob (≤ 16 KB) can be attached for
audit or research purposes.
A successful call returns the next visual frame(s) and updated
score/state.'
operationId: action7
security:
- ApiKeyAuth: []
requestBody:
description: Game/session identifiers plus optional reasoning data.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleActionCommand'
examples:
action:
value:
game_id: ls20-016295f7601e
guid: 2fa5332c-2e55-4825-b5c5-df960d504470
reasoning:
policy: π_left
responses:
'200':
description: Frame returned after executing the action.
content:
application/json:
schema:
$ref: '#/components/schemas/FrameResponse'
examples:
frame:
value:
game_id: ls20-016295f7601e
guid: 2fa5332c-2e55-4825-b5c5-df960d504470
frame:
- - - 0
- 0
- 1
- …
- - …
state: NOT_FINISHED
levels_completed: 3
win_levels: 254
action_input:
id: 7
available_actions:
- 1
- 2
- 3
- 4
- 7
'400':
description: "Bad request - possible causes: \n• Unknown `game_id` or invalid format \n• `guid` not found or does not belong to `game_id` \n• `reasoning` field exceeds 16 KB or is malformed\n"
'401':
description: Missing or invalid **X-API-Key** header.
components:
schemas:
ComplexActionCommand:
type: object
description: '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.
**Important:** Include any cookies (especially `AWSALB*` cookies) received from previous RESET or ACTION responses to ensure session affinity.
'
properties:
game_id:
type: string
description: Identifier of the game receiving this action.
guid:
type: string
description: Server-generated session ID obtained from the RESET call.
x:
type: integer
minimum: 0
maximum: 63
description: Horizontal coordinate on the game grid (0 = left, 63 = right).
y:
type: integer
minimum: 0
maximum: 63
description: Vertical coordinate on the game grid (0 = top, 63 = bottom).
reasoning:
type: object
description: '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.
'
additionalProperties: true
required:
- game_id
- guid
- x
- y
SimpleActionCommand:
type: object
description: 'Issues a one-parameter action (ACTION1 - ACTION5) to a running
game instance identified by `guid`.
**Important:** Include any cookies (especially `AWSALB*` cookies) received from previous RESET or ACTION responses to ensure session affinity.
'
properties:
game_id:
type: string
description: Game identifier this action targets.
guid:
type: string
description: Server-generated session ID obtained from a RESET response.
reasoning:
type: object
description: '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.
'
additionalProperties: true
required:
- game_id
- guid
FrameResponse:
type: object
description: "Snapshot returned after every RESET or ACTION command. \nIncludes the latest visual frame(s), cumulative score details, the\ncurrent game state, and an echo of the triggering action.\n"
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:\n\n• **NOT_FINISHED** - game in progress, not yet WIN or GAME_OVER. \n• **NOT_STARTED** - session has ended (WIN or GAME_OVER) and requires RESET. \n• **WIN** - session ended in victory. \n• **GAME_OVER** - session ended in defeat.\n"
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
ResetCommand:
type: object
description: "Starts a new game session **or** resets an existing one, depending on\nwhether a `guid` is supplied.\n\n• **No `guid` (null/empty)** → A brand-new game instance is created and\n the response will include its freshly minted `guid`.\n\n• **With `guid`** → The server issues a reset to that specific\n instance:\n - If at least one ACTION command has been executed in the **current\n level**, only that level is reset (typical “try again” behaviour).\n - If no ACTION commands have been executed since the last level\n transition, the entire game is reset to its initial state.\n\nSending two RESET commands back-to-back therefore always yields a\ncompletely fresh game.\n\nAll plays should be associated with an open scorecard via `card_id`\nso aggregated results can be tracked.\n"
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
- 'null'
description: "Server-generated game session ID. \n• Omit or set to `null` to create a new game. \n• Provide an existing value to reset that game as described above.\n"
required:
- game_id
- card_id
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key