> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcprize.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Open scorecard

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




## OpenAPI

````yaml /arc3v1.yaml post /api/scorecard/open
openapi: 3.0.3
info:
  title: ARC‑AGI‑3 REST 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.

    All requests **require** an `X‑API‑Key` header issued from the ARC‑AGI‑3 web
    console.


    **Important: Session Affinity via Cookies**  

    Games 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.
servers:
  - url: https://three.arcprize.org
security: []
tags:
  - name: Games
  - name: Scorecards
  - name: Commands
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
      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.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    OpenScorecardRequest:
      type: object
      description: |
        Optional metadata sent when opening a scorecard.  
        Every field is optional; omit any you don't need.  
        Use this to attach provenance links, free-form tags, or an
        “opaque” JSON blob describing the run (e.g. model settings,
        hyper-parameters, experiment notes). The opaque payload must not
        exceed 16 KB once serialized.
      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
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````