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