Arc Prize Foundation Scorecards API
The Scorecards API from Arc Prize Foundation — 4 operation(s) for scorecards.
OpenAPI Specification
openapi: 3.0.3
info:
title: ARC‑AGI‑3 REST Commands Scorecards 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.\nAll requests **require** an `X‑API‑Key` header issued from the ARC‑AGI‑3 web console.\n\n**Important: Session Affinity via Cookies** \nGames 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.\n"
servers:
- url: https://three.arcprize.org
tags:
- name: Scorecards
paths:
/api/scorecard/open:
post:
tags:
- Scorecards
summary: Open scorecard
description: 'Creates a new scorecard to aggregate statistics across one or more
plays. The server returns a `card_id`, which must be included in all
subsequent RESET commands and in the final **/scorecard/close** call.
You may attach optional metadata (URL, tags, opaque JSON) that will
be echoed back in summary responses.
'
operationId: openScorecard
security:
- ApiKeyAuth: []
requestBody:
description: Optional metadata to associate with the new scorecard.
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/OpenScorecardRequest'
examples:
minimal:
summary: Minimal request
value: {}
full:
summary: With tags, link, and opaque blob
value:
source_url: https://github.com/example/agent
tags:
- baseline
- gpt-4o
opaque:
model: gpt-4o
temperature: 0.25
responses:
'200':
description: scorecard successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/OpenScorecardResponse'
examples:
success:
value:
card_id: 8bb3b1b8-4b46-4a29-a13b-ad7850a0f916
'401':
description: Missing or invalid **X-API-Key** header.
/api/scorecard/close:
post:
tags:
- Scorecards
summary: Close scorecard
description: "Finalises a previously opened scorecard, locking its data and\nreturning the aggregate results. \nAfter a scorecard is closed, additional RESET or ACTION commands\nusing its `card_id` are rejected. \nYou must supply the `card_id` obtained from **/scorecard/open**.\n"
operationId: closeScorecard
security:
- ApiKeyAuth: []
requestBody:
description: Identifier of the scorecard to close.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CloseScorecardRequest'
examples:
example:
value:
card_id: 8bb3b1b8-4b46-4a29-a13b-ad7850a0f916
responses:
'200':
description: scorecard closed; final aggregate results returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ScorecardSummary'
examples:
success:
value:
card_id: 8ae52f21-b40c-457b-9f4e-65bd8381e67f
score: 100
source_url: https://sandbox.internal.arc-prize.com
tags:
- human
user_name: distracted_poincare
user_id: 102214435702678430912@google
published_at: '2026-01-26T23:34:57.097896Z'
environments:
- id: am92-80effacb
runs:
- id: am92-80effacb
guid: 4a38a278-796b-4f42-a28b-a27a68dbf862
score: 100
levels_completed: 5
actions: 136
resets: 0
state: WIN
completed: true
level_scores:
- 100
- 100
- 100
- 100
- 100
level_actions:
- 12
- 34
- 41
- 26
- 23
level_baseline_actions:
- 20
- 40
- 50
- 55
- 60
number_of_levels: 0
number_of_environments: 0
score: 100
actions: 136
levels_completed: 5
completed: true
level_count: 5
resets: 0
tags_scores:
- id: change9
guid: d3a0a4d8-536c-479d-b5a8-10bf1dc8aee3
score: 100
levels_completed: 5
actions: 136
resets: 0
state: NOT_FINISHED
completed: false
number_of_levels: 5
number_of_environments: 1
- id: example
guid: 66fe6b58-adf8-45b1-ac73-70ed486e22d0
score: 100
levels_completed: 5
actions: 136
resets: 0
state: NOT_FINISHED
completed: false
number_of_levels: 5
number_of_environments: 1
open_at: '2026-01-26T23:34:18.213873Z'
last_update: '2026-01-26T23:34:53.229182Z'
total_environments_completed: 1
total_environments: 1
total_levels_completed: 5
total_levels: 5
total_actions: 136
'401':
description: Missing or invalid **X-API-Key** header.
'404':
description: Supplied `card_id` does not correspond to an open scorecard.
/api/scorecard/{card_id}:
get:
tags:
- Scorecards
summary: Retrieve scorecard
description: "Returns the current (or final) statistics for the specified\nscorecard. \nThis works for both open and already-closed scorecards, making it\nuseful for polling progress or fetching archived results.\n"
operationId: getScorecard
security:
- ApiKeyAuth: []
parameters:
- name: card_id
in: path
required: true
description: Identifier returned by **/scorecard/open**.
schema:
type: string
responses:
'200':
description: scorecard found; summary returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ScorecardSummary'
examples:
example:
value:
card_id: 8ae52f21-b40c-457b-9f4e-65bd8381e67f
score: 100
source_url: https://sandbox.internal.arc-prize.com
tags:
- human
user_name: distracted_poincare
user_id: 102214435702678430912@google
open_at: '2026-01-26T23:34:18.213873Z'
last_update: '2026-01-26T23:34:53.229182Z'
total_environments_completed: 1
total_environments: 1
total_levels_completed: 5
total_levels: 5
total_actions: 136
environments: []
tags_scores: []
'401':
description: Missing or invalid **X-API-Key** header.
'404':
description: No open or closed scorecard found with the supplied `card_id`.
/api/scorecard/{card_id}/{game_id}:
get:
tags:
- Scorecards
summary: Retrieve scorecard (one game)
description: 'Returns the scorecard statistics **limited to a single environment**.
Only the entry matching `game_id` is present in `environments`; all
top-level counters are recomputed for that environment alone.
Useful for dashboards that present per-game progress without
fetching the full scorecard payload.
'
operationId: getScorecardForGame
security:
- ApiKeyAuth: []
parameters:
- name: card_id
in: path
required: true
description: Identifier returned by **/scorecard/open**.
schema:
type: string
- name: game_id
in: path
required: true
description: Game identifier to filter by (e.g. `ls20-1d57d6daeb05`).
schema:
type: string
responses:
'200':
description: scorecard found; statistics for the requested game.
content:
application/json:
schema:
$ref: '#/components/schemas/ScorecardSummary'
examples:
example:
value:
card_id: 8ae52f21-b40c-457b-9f4e-65bd8381e67f
score: 100
source_url: https://sandbox.internal.arc-prize.com
tags:
- human
user_name: distracted_poincare
user_id: 102214435702678430912@google
open_at: '2026-01-26T23:34:18.213873Z'
last_update: '2026-01-26T23:34:53.229182Z'
total_environments_completed: 1
total_environments: 1
total_levels_completed: 5
total_levels: 5
total_actions: 136
environments:
- id: ft09-1d57d6daeb05
runs:
- id: ft09-1d57d6daeb05
guid: 66fe6b58-adf8-45b1-ac73-70ed486e22d0
score: 3
levels_completed: 2
actions: 478
resets: 0
state: WIN
completed: true
level_scores:
- 1
- 2
level_actions:
- 171
- 307
level_baseline_actions:
- 200
- 250
number_of_levels: 5
number_of_environments: 1
score: 3
actions: 478
levels_completed: 2
completed: true
level_count: 5
resets: 0
tags_scores: []
'401':
description: Missing or invalid **X-API-Key** header.
'404':
description: 'Either the supplied `card_id` does not exist, or the
scorecard contains no entry for the specified `game_id`.
'
components:
schemas:
OpenScorecardResponse:
type: object
description: 'Response returned after a successful “open scorecard” request.
Contains the server-generated identifier for this tracked run.
'
properties:
card_id:
type: string
description: Globally unique ID for the newly opened scorecard.
required:
- card_id
TagScore:
type: object
description: Per-tag aggregate statistics for runs that were tagged (e.g. for filtering).
properties:
id:
type: string
description: Tag or run identifier.
guid:
type: string
description: Session id associated with this tag entry.
score:
type: integer
description: Aggregate score for this tag.
levels_completed:
type: integer
description: Levels completed for this tag.
actions:
type: integer
description: Total actions for this tag.
resets:
type: integer
description: Resets for this tag.
state:
type: string
enum:
- NOT_FINISHED
- NOT_STARTED
- WIN
- GAME_OVER
description: Terminal state for this tag run, if applicable.
completed:
type: boolean
description: Whether this tag run reached a terminal state.
number_of_levels:
type: integer
description: Number of levels.
number_of_environments:
type: integer
description: Number of environments.
required:
- id
- guid
- score
- levels_completed
- actions
- resets
- state
- completed
- number_of_levels
- number_of_environments
RunSummary:
type: object
description: 'Statistics for a single run (one RESET → play until WIN/GAME_OVER or abandon)
within an environment. Arrays `level_scores`, `level_actions`, and
`level_baseline_actions` align by index (one entry per level).
'
properties:
id:
type: string
description: Environment id this run belongs to.
guid:
type: string
description: Server-generated session id for this run.
score:
type: integer
description: Score achieved in this run (0–254).
levels_completed:
type: integer
description: Number of levels completed in this run.
actions:
type: integer
description: Number of actions taken in this run.
resets:
type: integer
description: Number of resets (level or full) in this run.
state:
type: string
description: "Final state of the run:\n• **NOT_FINISHED** - run is active. \n• **NOT_STARTED** - run has ended and would need RESET to continue. \n• **WIN** - run ended in victory. \n• **GAME_OVER** - run ended in defeat.\n"
enum:
- NOT_FINISHED
- NOT_STARTED
- WIN
- GAME_OVER
completed:
type: boolean
description: Whether the run reached a terminal state (WIN or GAME_OVER).
level_scores:
type: array
description: Score achieved at each level (positional).
items:
type: integer
level_actions:
type: array
description: Actions taken at each level (positional).
items:
type: integer
level_baseline_actions:
type: array
description: Baseline (e.g. par) actions per level, when defined (positional).
items:
type: integer
number_of_levels:
type: integer
description: Number of levels in this environment (may be 0 if not applicable).
number_of_environments:
type: integer
description: Number of environments (may be 0 if not applicable).
required:
- id
- guid
- score
- levels_completed
- actions
- resets
- state
- completed
OpenScorecardRequest:
type: object
description: "Optional metadata sent when opening a scorecard. \nEvery field is optional; omit any you don't need. \nUse this to attach provenance links, free-form tags, or an\n“opaque” JSON blob describing the run (e.g. model settings,\nhyper-parameters, experiment notes). The opaque payload must not\nexceed 16 KB once serialized.\n"
properties:
source_url:
type: string
format: uri
description: Link to code, notebook, or write-up associated with the run.
tags:
type: array
description: Arbitrary labels for later filtering and aggregation.
items:
type: string
opaque:
type: object
description: 'Free-form JSON data (≤ 16 KB). Stored verbatim; the service
does not inspect or validate its structure.
'
additionalProperties: true
CloseScorecardRequest:
type: object
description: 'Payload for closing a previously opened scorecard and finalising
its aggregated results.
'
properties:
card_id:
type: string
description: 'Identifier of the scorecard to close—use the `card_id`
returned by **OpenScorecardResponse**.
'
required:
- card_id
EnvironmentSummary:
type: object
description: "Statistics for one environment (game) inside a scorecard. \nContains aggregate counts and an array of `runs` (one per RESET/play).\n"
properties:
id:
type: string
description: Environment/game identifier (e.g. `am92-80effacb`).
runs:
type: array
description: One entry per run (RESET) in this environment.
items:
$ref: '#/components/schemas/RunSummary'
score:
type: integer
description: Aggregate score for this environment.
actions:
type: integer
description: Total actions taken in this environment across all runs.
levels_completed:
type: integer
description: Levels completed in this environment.
completed:
type: boolean
description: Whether this environment reached a terminal state (WIN or GAME_OVER).
level_count:
type: integer
description: Number of levels in this environment.
resets:
type: integer
description: Number of RESETs (level or full) in this environment.
required:
- id
- runs
- score
- actions
- levels_completed
- completed
- level_count
- resets
ScorecardSummary:
type: object
description: "Aggregate results for an entire scorecard run. \nReturned when closing a scorecard or when retrieving a scorecard (open or closed).\nIncludes cumulative totals, optional metadata echoed from the open request\n(e.g. `source_url`, `tags`, `opaque`), user identity (`user_name`, `user_id`),\ntimestamps (`open_at`, `last_update`, `published_at`), and a per-environment\nbreakdown in `environments`. The `tags_scores` array provides per-tag aggregates\nfor runs that were tagged.\n"
properties:
card_id:
type: string
description: The scorecard ID returned by **OpenScorecardResponse**.
score:
type: integer
description: Aggregate score for this scorecard (sum of per-level scores).
source_url:
type: string
format: uri
description: Link originally supplied in the **OpenScorecardRequest**.
tags:
type: array
description: Arbitrary labels echoed back from the open request.
items:
type: string
user_name:
type: string
description: Display name of the user who opened/ran this scorecard.
user_id:
type: string
description: Stable identifier of the user (e.g. provider subject id).
published_at:
type: string
format: date-time
description: When the scorecard was closed/published (absent if still open).
environments:
type: array
description: Per-environment breakdown; each entry is one game/environment with its runs.
items:
$ref: '#/components/schemas/EnvironmentSummary'
opaque:
type: object
description: 'Free-form JSON blob (≤ 16 KB) exactly as provided when the
scorecard was opened. Absent if none was supplied.
'
additionalProperties: true
tags_scores:
type: array
description: Per-tag aggregate statistics for runs that were tagged.
items:
$ref: '#/components/schemas/TagScore'
open_at:
type: string
format: date-time
description: When the scorecard was opened.
last_update:
type: string
format: date-time
description: When the scorecard was last updated (e.g. last action or close).
total_environments_completed:
type: integer
description: Number of environments that reached a terminal state (WIN or GAME_OVER).
total_environments:
type: integer
description: Total number of environments in this scorecard.
total_levels_completed:
type: integer
description: Cumulative levels completed across all runs.
total_levels:
type: integer
description: Total number of levels across all environments.
total_actions:
type: integer
description: Cumulative number of actions taken across all plays.
required:
- card_id
- score
- environments
- open_at
- last_update
- total_environments_completed
- total_environments
- total_levels_completed
- total_levels
- total_actions
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key