{
  "openapi": "3.1.1",
  "info": {
    "title": "CGS Games API",
    "version": "1.0.0",
    "description": "Discover community Card Game Simulator games. Public reads require no authentication. Publishing and deletion use Firebase ID tokens and a user profile with a username. API errors retain the legacy error string and add code, message, and hint. GET routes also support HEAD; OPTIONS lists allowed methods. Unknown API paths return JSON 404; unsupported methods return JSON 405 with Allow. Select major version 1 with API-Version: 1 (also the default). Unsupported versions return 400. Breaking changes require a new major version; at least 90 days notice precedes retirement using Deprecation (RFC 9745), Sunset (RFC 8594), and a migration Link. Version 1 has no scheduled retirement. See /developers#versioning.",
    "contact": {
      "name": "CGS Games support",
      "url": "https://cgs.games/contact",
      "email": "david@finoldigital.com"
    }
  },
  "servers": [
    {
      "url": "https://cgs.games"
    }
  ],
  "externalDocs": {
    "description": "CGS Games developer portal: quickstart, authentication, sandbox and versioning",
    "url": "https://cgs.games/developers"
  },
  "security": [],
  "paths": {
    "/api/games": {
      "get": {
        "operationId": "listGames",
        "summary": "List the newest public games",
        "responses": {
          "200": {
            "description": "Up to 100 public games ordered by uploadedAt descending; private (unlisted) games are omitted. No pagination or query filters.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "maxItems": 100,
                  "items": {
                    "$ref": "#/components/schemas/Game"
                  }
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or unsupported API version.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "500": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "List the newest public games. Private games are omitted but remain reachable at their /{username}/{slug} page. See https://cgs.games/developers for integration guidance."
      },
      "post": {
        "operationId": "publishGame",
        "summary": "Publish a game from its auto-update URL",
        "security": [
          {
            "firebaseIdToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["autoUpdateUrl"],
                "properties": {
                  "autoUpdateUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Public HTTPS URL on port 443 without embedded credentials, serving a CGS JSON game specification including name and optional bannerImageUrl, cardBackImageUrl, and copyright. Private or reserved destinations are rejected, including after redirects. Up to five redirects and a 16 MiB response body are accepted.",
                    "pattern": "^https://"
                  },
                  "visibility": {
                    "type": "string",
                    "enum": ["public", "private"],
                    "default": "public",
                    "description": "public lists the game in catalogs; private publishes it unlisted, open only to people with its /{username}/{slug} page link."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Game published successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublishedGame"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "400": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "401": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "403": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "404": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "409": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "500": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "502": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Publish a game from its auto-update URL. The specification must be a JSON object with a string name. Each creator may publish at most 50 games (403 GAME_QUOTA_EXCEEDED). Game names are limited to 200 characters and copyright notices to 500; both must be strings. A creator cannot publish two games with the same slug (409). See https://cgs.games/developers for integration guidance."
      },
      "head": {
        "operationId": "listGamesHeaders",
        "summary": "Read headers for list the newest games",
        "description": "Same authentication, query parameters and processing as GET, without a response body.",
        "responses": {
          "200": {
            "description": "Up to 100 games ordered by uploadedAt descending; no pagination or query filters.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or unsupported API version; no response body.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "500": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        }
      },
      "options": {
        "operationId": "optionsapigames",
        "summary": "Discover allowed methods and CORS preflight permissions",
        "security": [],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Origin of the requesting browser."
          },
          {
            "name": "Access-Control-Request-Method",
            "in": "header",
            "schema": {
              "type": "string",
              "enum": ["GET", "HEAD", "POST"]
            },
            "description": "Method requested by a browser preflight."
          },
          {
            "name": "Access-Control-Request-Headers",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "example": "Content-Type, Authorization",
            "description": "Access-Control-Request-Headers request value."
          }
        ],
        "responses": {
          "204": {
            "description": "Preflight accepted with no response body.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string"
                },
                "example": "GET, HEAD, POST, OPTIONS"
              },
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string",
                  "const": "*"
                }
              },
              "Access-Control-Allow-Methods": {
                "schema": {
                  "type": "string"
                },
                "example": "GET, HEAD, POST, OPTIONS"
              },
              "Access-Control-Allow-Headers": {
                "schema": {
                  "type": "string"
                },
                "example": "Content-Type, Authorization, API-Version"
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Discover allowed methods and CORS preflight permissions. See https://cgs.games/developers for integration guidance."
      },
      "parameters": [
        {
          "name": "API-Version",
          "in": "header",
          "required": false,
          "description": "Major API version. Omit for version 1; any other value returns 400 UNSUPPORTED_API_VERSION. See /developers#versioning.",
          "schema": {
            "type": "string",
            "enum": ["1"],
            "default": "1"
          }
        }
      ]
    },
    "/api/browse": {
      "get": {
        "operationId": "browseGames",
        "summary": "Legacy alias for the game catalog",
        "responses": {
          "200": {
            "description": "Up to 100 games ordered by uploadedAt descending; no pagination or query filters.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "maxItems": 100,
                  "items": {
                    "$ref": "#/components/schemas/Game"
                  }
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or unsupported API version.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "500": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Legacy alias for the game catalog. See https://cgs.games/developers for integration guidance."
      },
      "head": {
        "operationId": "browseGamesHeaders",
        "summary": "Read headers for legacy alias for the game catalog",
        "description": "Same authentication, query parameters and processing as GET, without a response body.",
        "responses": {
          "200": {
            "description": "Up to 100 games ordered by uploadedAt descending; no pagination or query filters.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or unsupported API version; no response body.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "500": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        }
      },
      "options": {
        "operationId": "optionsapibrowse",
        "summary": "Discover allowed methods and CORS preflight permissions",
        "security": [],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Origin of the requesting browser."
          },
          {
            "name": "Access-Control-Request-Method",
            "in": "header",
            "schema": {
              "type": "string",
              "enum": ["GET", "HEAD"]
            },
            "description": "Method requested by a browser preflight."
          },
          {
            "name": "Access-Control-Request-Headers",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "example": "Content-Type, Authorization",
            "description": "Access-Control-Request-Headers request value."
          }
        ],
        "responses": {
          "204": {
            "description": "Preflight accepted with no response body.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string"
                },
                "example": "GET, HEAD, OPTIONS"
              },
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string",
                  "const": "*"
                }
              },
              "Access-Control-Allow-Methods": {
                "schema": {
                  "type": "string"
                },
                "example": "GET, HEAD, OPTIONS"
              },
              "Access-Control-Allow-Headers": {
                "schema": {
                  "type": "string"
                },
                "example": "Content-Type, Authorization, API-Version"
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Discover allowed methods and CORS preflight permissions. See https://cgs.games/developers for integration guidance."
      },
      "parameters": [
        {
          "name": "API-Version",
          "in": "header",
          "required": false,
          "description": "Major API version. Omit for version 1; any other value returns 400 UNSUPPORTED_API_VERSION. See /developers#versioning.",
          "schema": {
            "type": "string",
            "enum": ["1"],
            "default": "1"
          }
        }
      ]
    },
    "/api/games/mine": {
      "parameters": [
        {
          "name": "API-Version",
          "in": "header",
          "required": false,
          "description": "Major API version. Omit for version 1; any other value returns 400 UNSUPPORTED_API_VERSION. See /developers#versioning.",
          "schema": {
            "type": "string",
            "enum": ["1"],
            "default": "1"
          }
        }
      ],
      "get": {
        "operationId": "listMyGames",
        "summary": "List the authenticated creator's games, including private games",
        "security": [
          {
            "firebaseIdToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Up to 100 of your games, public and private, ordered by uploadedAt descending.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "maxItems": 100,
                  "items": {
                    "$ref": "#/components/schemas/Game"
                  }
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "401": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "403": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "404": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "500": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "List the authenticated creator's games, including private games omitted from GET /api/games. See https://cgs.games/developers for integration guidance."
      },
      "head": {
        "operationId": "listMyGamesHeaders",
        "summary": "Read headers for list the authenticated creator's games",
        "security": [
          {
            "firebaseIdToken": []
          }
        ],
        "description": "Same authentication, query parameters and processing as GET, without a response body.",
        "responses": {
          "200": {
            "description": "Up to 100 of your games, public and private, ordered by uploadedAt descending.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "401": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "403": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "404": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "500": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        }
      },
      "options": {
        "operationId": "optionsapigamesmine",
        "summary": "Discover allowed methods and CORS preflight permissions",
        "security": [],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Origin of the requesting browser."
          },
          {
            "name": "Access-Control-Request-Method",
            "in": "header",
            "schema": {
              "type": "string",
              "enum": ["GET", "HEAD"]
            },
            "description": "Method requested by a browser preflight."
          },
          {
            "name": "Access-Control-Request-Headers",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "example": "Content-Type, Authorization",
            "description": "Access-Control-Request-Headers request value."
          }
        ],
        "responses": {
          "204": {
            "description": "Preflight accepted with no response body.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string"
                },
                "example": "GET, HEAD, OPTIONS"
              },
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string",
                  "const": "*"
                }
              },
              "Access-Control-Allow-Methods": {
                "schema": {
                  "type": "string"
                },
                "example": "GET, HEAD, OPTIONS"
              },
              "Access-Control-Allow-Headers": {
                "schema": {
                  "type": "string"
                },
                "example": "Content-Type, Authorization, API-Version"
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Discover allowed methods and CORS preflight permissions. See https://cgs.games/developers for integration guidance."
      }
    },
    "/api/games/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Firestore game document ID from the catalog, not a game slug.",
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "API-Version",
          "in": "header",
          "required": false,
          "description": "Major API version. Omit for version 1; any other value returns 400 UNSUPPORTED_API_VERSION. See /developers#versioning.",
          "schema": {
            "type": "string",
            "enum": ["1"],
            "default": "1"
          }
        }
      ],
      "patch": {
        "operationId": "updateGameVisibility",
        "summary": "Change the visibility of a game owned by the authenticated creator",
        "security": [
          {
            "firebaseIdToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GameVisibilityUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Visibility updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GameVisibilityUpdated"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "400": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "401": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "403": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "404": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "500": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Make an owned game public (listed) or private (unlisted but open by link). See https://cgs.games/developers for integration guidance."
      },
      "delete": {
        "operationId": "deleteGame",
        "summary": "Delete a game owned by the authenticated creator",
        "security": [
          {
            "firebaseIdToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Game deleted. Existing success response is plain text.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "Game deleted successfully"
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "400": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "401": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "403": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "404": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "500": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Delete a game owned by the authenticated creator. See https://cgs.games/developers for integration guidance."
      },
      "options": {
        "operationId": "optionsapigamesid",
        "summary": "Discover allowed methods and CORS preflight permissions",
        "security": [],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Origin of the requesting browser."
          },
          {
            "name": "Access-Control-Request-Method",
            "in": "header",
            "schema": {
              "type": "string",
              "enum": ["PATCH", "DELETE"]
            },
            "description": "Method requested by a browser preflight."
          },
          {
            "name": "Access-Control-Request-Headers",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "example": "Content-Type, Authorization",
            "description": "Access-Control-Request-Headers request value."
          }
        ],
        "responses": {
          "204": {
            "description": "Preflight accepted with no response body.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string"
                },
                "example": "PATCH, DELETE, OPTIONS"
              },
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string",
                  "const": "*"
                }
              },
              "Access-Control-Allow-Methods": {
                "schema": {
                  "type": "string"
                },
                "example": "PATCH, DELETE, OPTIONS"
              },
              "Access-Control-Allow-Headers": {
                "schema": {
                  "type": "string"
                },
                "example": "Content-Type, Authorization, API-Version"
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Discover allowed methods and CORS preflight permissions. See https://cgs.games/developers for integration guidance."
      }
    },
    "/api/games/upload": {
      "post": {
        "operationId": "uploadGame",
        "summary": "Publish a .cgs.zip archive (maximum 100 MiB)",
        "description": "Send a multipart file directly, or first upload the archive to Firebase Storage using an authenticated client and then submit its staged path. A staged archive is cleaned up after processing is attempted. Archives need a valid cgs.json and supported game assets. Archives may contain at most 20000 entries (413 TOO_MANY_FILES) and expand to at most 256 MiB, with no single file over 64 MiB (413 ARCHIVE_TOO_LARGE or ENTRY_TOO_LARGE). Each creator may store up to 1 GiB of published files (413 STORAGE_QUOTA_EXCEEDED). Each creator may publish at most 50 games (403 GAME_QUOTA_EXCEEDED). Game names are limited to 200 characters and copyright notices to 500; both must be strings.",
        "security": [
          {
            "firebaseIdToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": ".cgs.zip archive, at most 104857600 bytes."
                  },
                  "visibility": {
                    "type": "string",
                    "enum": ["public", "private"],
                    "default": "public",
                    "description": "public lists the game in catalogs; private publishes it unlisted, open only to people with its /{username}/{slug} page link."
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["stagedPath", "originalFilename"],
                "properties": {
                  "stagedPath": {
                    "type": "string",
                    "pattern": "^staged-uploads/[^/]+/[A-Za-z0-9_-]+\\.cgs\\.zip$",
                    "description": "staged-uploads/{authenticated Firebase uid}/{unique-id}.cgs.zip"
                  },
                  "originalFilename": {
                    "type": "string",
                    "pattern": "\\.cgs\\.zip$"
                  },
                  "visibility": {
                    "type": "string",
                    "enum": ["public", "private"],
                    "default": "public",
                    "description": "public lists the game in catalogs; private publishes it unlisted, open only to people with its /{username}/{slug} page link."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Game published successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublishedGame"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "400": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "401": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "403": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "404": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "409": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "413": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "500": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        }
      },
      "options": {
        "operationId": "optionsapigamesupload",
        "summary": "Discover allowed methods and CORS preflight permissions",
        "security": [],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Origin of the requesting browser."
          },
          {
            "name": "Access-Control-Request-Method",
            "in": "header",
            "schema": {
              "type": "string",
              "enum": ["POST"]
            },
            "description": "Method requested by a browser preflight."
          },
          {
            "name": "Access-Control-Request-Headers",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "example": "Content-Type, Authorization",
            "description": "Access-Control-Request-Headers request value."
          }
        ],
        "responses": {
          "204": {
            "description": "Preflight accepted with no response body.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string"
                },
                "example": "POST, OPTIONS"
              },
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string",
                  "const": "*"
                }
              },
              "Access-Control-Allow-Methods": {
                "schema": {
                  "type": "string"
                },
                "example": "POST, OPTIONS"
              },
              "Access-Control-Allow-Headers": {
                "schema": {
                  "type": "string"
                },
                "example": "Content-Type, Authorization, API-Version"
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Discover allowed methods and CORS preflight permissions. See https://cgs.games/developers for integration guidance."
      },
      "parameters": [
        {
          "name": "API-Version",
          "in": "header",
          "required": false,
          "description": "Major API version. Omit for version 1; any other value returns 400 UNSUPPORTED_API_VERSION. See /developers#versioning.",
          "schema": {
            "type": "string",
            "enum": ["1"],
            "default": "1"
          }
        }
      ]
    },
    "/api/gatcg_spoilers": {
      "get": {
        "operationId": "getGrandArchiveSpoilers",
        "summary": "Read cached Grand Archive spoiler card data",
        "description": "Normally reads the assembled cache. Rate limited to 10 requests per minute per client IP per running instance. Operators may use warm=1 with the separate GATCG_WARM_TOKEN Bearer secret in production; a Firebase ID token does not grant this access. Unauthorized nocache=1 is ignored. warm runs can take up to 240 seconds and are not rate limited.",
        "parameters": [
          {
            "name": "warm",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["1"]
            },
            "description": "Operator-only cache rebuild; requires the warmToken security scheme in production."
          },
          {
            "name": "refresh",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["1"]
            },
            "description": "Re-run OCR from scratch. Only applies with warm=1."
          },
          {
            "name": "nocache",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["1"]
            },
            "description": "Operator-only assembled cache bypass, preserving the OCR cache. Ignored without operator authorization."
          }
        ],
        "security": [
          {},
          {
            "warmToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Spoiler cards in a data array. Pending OCR may leave effect_raw empty.",
            "headers": {
              "X-Cache": {
                "schema": {
                  "type": "string",
                  "enum": ["hit", "miss", "warm", "stale"]
                },
                "description": "Cache result."
              },
              "X-Ocr-Pending": {
                "schema": {
                  "type": "integer",
                  "minimum": 0
                },
                "description": "Cards awaiting OCR."
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              },
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 quota policy. Present for normal rate-limited reads, not authorized warm runs.",
                "schema": {
                  "type": "string"
                },
                "example": "\"spoilers\";q=10;w=60"
              },
              "RateLimit": {
                "description": "IETF draft structured field: r is remaining requests; t is seconds until reset. Per IP per running instance. Normal rate-limited reads only.",
                "schema": {
                  "type": "string"
                },
                "example": "\"spoilers\";r=9;t=60"
              },
              "X-RateLimit-Limit": {
                "description": "Legacy request quota.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Legacy remaining requests.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Reset": {
                "description": "Legacy absolute reset time (ISO 8601), unlike the relative t in RateLimit.",
                "schema": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SpoilerCard"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or unsupported API version.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "401": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "429": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Wait at least this many seconds before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              },
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 quota policy. Present for normal rate-limited reads, not authorized warm runs.",
                "schema": {
                  "type": "string"
                },
                "example": "\"spoilers\";q=10;w=60"
              },
              "RateLimit": {
                "description": "IETF draft structured field: r is remaining requests; t is seconds until reset. Per IP per running instance. Normal rate-limited reads only.",
                "schema": {
                  "type": "string"
                },
                "example": "\"spoilers\";r=9;t=60"
              },
              "X-RateLimit-Limit": {
                "description": "Legacy request quota.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Legacy remaining requests.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Reset": {
                "description": "Legacy absolute reset time (ISO 8601), unlike the relative t in RateLimit.",
                "schema": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "502": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              },
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 quota policy. Present for normal rate-limited reads, not authorized warm runs.",
                "schema": {
                  "type": "string"
                },
                "example": "\"spoilers\";q=10;w=60"
              },
              "RateLimit": {
                "description": "IETF draft structured field: r is remaining requests; t is seconds until reset. Per IP per running instance. Normal rate-limited reads only.",
                "schema": {
                  "type": "string"
                },
                "example": "\"spoilers\";r=9;t=60"
              },
              "X-RateLimit-Limit": {
                "description": "Legacy request quota.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Legacy remaining requests.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Reset": {
                "description": "Legacy absolute reset time (ISO 8601), unlike the relative t in RateLimit.",
                "schema": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        }
      },
      "head": {
        "operationId": "getGrandArchiveSpoilersHeaders",
        "summary": "Read headers for read cached grand archive spoiler card data",
        "description": "Same authentication, query parameters and processing as GET, without a response body.",
        "security": [
          {},
          {
            "warmToken": []
          }
        ],
        "parameters": [
          {
            "name": "warm",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["1"]
            },
            "description": "Operator-only cache rebuild; requires the warmToken security scheme in production."
          },
          {
            "name": "refresh",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["1"]
            },
            "description": "Re-run OCR from scratch. Only applies with warm=1."
          },
          {
            "name": "nocache",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["1"]
            },
            "description": "Operator-only assembled cache bypass, preserving the OCR cache. Ignored without operator authorization."
          }
        ],
        "responses": {
          "200": {
            "description": "Spoiler cards in a data array. Pending OCR may leave effect_raw empty.",
            "headers": {
              "X-Cache": {
                "schema": {
                  "type": "string",
                  "enum": ["hit", "miss", "warm", "stale"]
                },
                "description": "Cache result."
              },
              "X-Ocr-Pending": {
                "schema": {
                  "type": "integer",
                  "minimum": 0
                },
                "description": "Cards awaiting OCR."
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              },
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 quota policy. Present for normal rate-limited reads, not authorized warm runs.",
                "schema": {
                  "type": "string"
                },
                "example": "\"spoilers\";q=10;w=60"
              },
              "RateLimit": {
                "description": "IETF draft structured field: r is remaining requests; t is seconds until reset. Per IP per running instance. Normal rate-limited reads only.",
                "schema": {
                  "type": "string"
                },
                "example": "\"spoilers\";r=9;t=60"
              },
              "X-RateLimit-Limit": {
                "description": "Legacy request quota.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Legacy remaining requests.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Reset": {
                "description": "Legacy absolute reset time (ISO 8601), unlike the relative t in RateLimit.",
                "schema": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or unsupported API version; no response body.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "401": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "429": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "Retry-After": {
                "description": "Wait at least this many seconds before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              },
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 quota policy. Present for normal rate-limited reads, not authorized warm runs.",
                "schema": {
                  "type": "string"
                },
                "example": "\"spoilers\";q=10;w=60"
              },
              "RateLimit": {
                "description": "IETF draft structured field: r is remaining requests; t is seconds until reset. Per IP per running instance. Normal rate-limited reads only.",
                "schema": {
                  "type": "string"
                },
                "example": "\"spoilers\";r=9;t=60"
              },
              "X-RateLimit-Limit": {
                "description": "Legacy request quota.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Legacy remaining requests.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Reset": {
                "description": "Legacy absolute reset time (ISO 8601), unlike the relative t in RateLimit.",
                "schema": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "502": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              },
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 quota policy. Present for normal rate-limited reads, not authorized warm runs.",
                "schema": {
                  "type": "string"
                },
                "example": "\"spoilers\";q=10;w=60"
              },
              "RateLimit": {
                "description": "IETF draft structured field: r is remaining requests; t is seconds until reset. Per IP per running instance. Normal rate-limited reads only.",
                "schema": {
                  "type": "string"
                },
                "example": "\"spoilers\";r=9;t=60"
              },
              "X-RateLimit-Limit": {
                "description": "Legacy request quota.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Legacy remaining requests.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Reset": {
                "description": "Legacy absolute reset time (ISO 8601), unlike the relative t in RateLimit.",
                "schema": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        }
      },
      "options": {
        "operationId": "optionsapigatcgspoilers",
        "summary": "Discover allowed methods and CORS preflight permissions",
        "security": [],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Origin of the requesting browser."
          },
          {
            "name": "Access-Control-Request-Method",
            "in": "header",
            "schema": {
              "type": "string",
              "enum": ["GET", "HEAD"]
            },
            "description": "Method requested by a browser preflight."
          },
          {
            "name": "Access-Control-Request-Headers",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "example": "Content-Type, Authorization",
            "description": "Access-Control-Request-Headers request value."
          }
        ],
        "responses": {
          "204": {
            "description": "Preflight accepted with no response body.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string"
                },
                "example": "GET, HEAD, OPTIONS"
              },
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string",
                  "const": "*"
                }
              },
              "Access-Control-Allow-Methods": {
                "schema": {
                  "type": "string"
                },
                "example": "GET, HEAD, OPTIONS"
              },
              "Access-Control-Allow-Headers": {
                "schema": {
                  "type": "string"
                },
                "example": "Content-Type, Authorization, API-Version"
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Discover allowed methods and CORS preflight permissions. See https://cgs.games/developers for integration guidance."
      },
      "parameters": [
        {
          "name": "API-Version",
          "in": "header",
          "required": false,
          "description": "Major API version. Omit for version 1; any other value returns 400 UNSUPPORTED_API_VERSION. See /developers#versioning.",
          "schema": {
            "type": "string",
            "enum": ["1"],
            "default": "1"
          }
        }
      ]
    },
    "/api/proxy/{url}": {
      "parameters": [
        {
          "name": "url",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Upstream host and path without a scheme, for example example.com/assets/game.json. This catch-all path can contain slashes; requires public HTTPS on port 443. Private IPs, embedded credentials, and unsafe redirects are rejected. GET forwards query parameters. Responses are limited to 100 MiB with a 30-second deadline; POST bodies to 16 MiB. Responses stream as bytes arrive. A limit or connection failure after headers aborts the stream; discard partial content. Active content is sandboxed and upstream cookies are never forwarded. Only images (PNG, JPEG, GIF, WebP, AVIF, BMP, TIFF, ICO), JSON, plain text, CSV, and binary downloads (octet-stream, zip) are served; other upstream types, including HTML, SVG, XML and PDF, return 502 UNSUPPORTED_UPSTREAM_TYPE. Binary downloads carry Content-Disposition: attachment. Requests are limited to 600 per minute per client IP per running instance (429 with Retry-After); every optimized image requested through /_next/image counts toward the same limit."
        },
        {
          "name": "API-Version",
          "in": "header",
          "required": false,
          "description": "Major API version. Omit for version 1; any other value returns 400 UNSUPPORTED_API_VERSION. See /developers#versioning.",
          "schema": {
            "type": "string",
            "enum": ["1"],
            "default": "1"
          }
        }
      ],
      "get": {
        "operationId": "proxyGet",
        "summary": "Fetch an upstream HTTPS resource",
        "responses": {
          "200": {
            "description": "Upstream body and Content-Type: an image, JSON, plain text, CSV, or a binary download.",
            "content": {
              "*/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "400": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "429": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Wait at least this many seconds before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              },
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 quota policy.",
                "schema": {
                  "type": "string"
                },
                "example": "\"proxy\";q=600;w=60"
              },
              "RateLimit": {
                "description": "IETF draft structured field: r is remaining requests; t is seconds until reset. Per IP per running instance.",
                "schema": {
                  "type": "string"
                },
                "example": "\"proxy\";r=0;t=30"
              },
              "X-RateLimit-Limit": {
                "description": "Legacy request quota.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Legacy remaining requests.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Reset": {
                "description": "Legacy absolute reset time (ISO 8601), unlike the relative t in RateLimit.",
                "schema": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "502": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Fetch an upstream HTTPS resource. See https://cgs.games/developers for integration guidance. Upstream content is arbitrary, not a typed CGS function result; use catalog operations for structured game data."
      },
      "post": {
        "operationId": "proxyPost",
        "summary": "Forward a JSON body to an upstream HTTPS resource",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonValue"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful upstream response, including its headers and body.",
            "content": {
              "*/*": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "description": "Opaque upstream response bytes; inspect Content-Type before decoding."
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "400": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "429": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Wait at least this many seconds before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              },
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 quota policy.",
                "schema": {
                  "type": "string"
                },
                "example": "\"proxy\";q=600;w=60"
              },
              "RateLimit": {
                "description": "IETF draft structured field: r is remaining requests; t is seconds until reset. Per IP per running instance.",
                "schema": {
                  "type": "string"
                },
                "example": "\"proxy\";r=0;t=30"
              },
              "X-RateLimit-Limit": {
                "description": "Legacy request quota.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Legacy remaining requests.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Reset": {
                "description": "Legacy absolute reset time (ISO 8601), unlike the relative t in RateLimit.",
                "schema": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "502": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Forward a JSON body to an upstream HTTPS resource. See https://cgs.games/developers for integration guidance. Upstream content is arbitrary, not a typed CGS function result; use catalog operations for structured game data."
      },
      "head": {
        "operationId": "proxyGetHeaders",
        "summary": "Read headers for fetch an upstream https resource",
        "description": "Same authentication, query parameters and processing as GET, without a response body. Upstream content is arbitrary, not a typed CGS function result; use catalog operations for structured game data.",
        "responses": {
          "200": {
            "description": "Upstream body and Content-Type; may be JSON, an image, or other content.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "400": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "429": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Wait at least this many seconds before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              },
              "RateLimit-Policy": {
                "description": "IETF draft-ietf-httpapi-ratelimit-headers-11 quota policy.",
                "schema": {
                  "type": "string"
                },
                "example": "\"proxy\";q=600;w=60"
              },
              "RateLimit": {
                "description": "IETF draft structured field: r is remaining requests; t is seconds until reset. Per IP per running instance.",
                "schema": {
                  "type": "string"
                },
                "example": "\"proxy\";r=0;t=30"
              },
              "X-RateLimit-Limit": {
                "description": "Legacy request quota.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Legacy remaining requests.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "X-RateLimit-Reset": {
                "description": "Legacy absolute reset time (ISO 8601), unlike the relative t in RateLimit.",
                "schema": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "502": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        }
      },
      "options": {
        "operationId": "optionsapiproxyurl",
        "summary": "Discover allowed methods and CORS preflight permissions",
        "security": [],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Origin of the requesting browser."
          },
          {
            "name": "Access-Control-Request-Method",
            "in": "header",
            "schema": {
              "type": "string",
              "enum": ["GET", "HEAD", "POST"]
            },
            "description": "Method requested by a browser preflight."
          },
          {
            "name": "Access-Control-Request-Headers",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "example": "Content-Type, Authorization",
            "description": "Access-Control-Request-Headers request value."
          }
        ],
        "responses": {
          "204": {
            "description": "Preflight accepted with no response body.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string"
                },
                "example": "GET, HEAD, POST, OPTIONS"
              },
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string",
                  "const": "*"
                }
              },
              "Access-Control-Allow-Methods": {
                "schema": {
                  "type": "string"
                },
                "example": "GET, HEAD, POST, OPTIONS"
              },
              "Access-Control-Allow-Headers": {
                "schema": {
                  "type": "string"
                },
                "example": "Content-Type, Authorization, API-Version"
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Discover allowed methods and CORS preflight permissions. See https://cgs.games/developers for integration guidance. Upstream content is arbitrary, not a typed CGS function result; use catalog operations for structured game data."
      }
    },
    "/api/sandbox/games": {
      "get": {
        "operationId": "listSandboxGames",
        "summary": "Read a deterministic sandbox catalog",
        "responses": {
          "200": {
            "description": "A fixed example catalog matching the production Game schema.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "maxItems": 100,
                  "items": {
                    "$ref": "#/components/schemas/Game"
                  }
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or unsupported API version.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "500": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Read-only Game fixtures, with no authentication, database access, or production mutations. Example URLs and creators do not refer to playable games. No sandbox writes are supported."
      },
      "head": {
        "operationId": "listSandboxGamesHeaders",
        "summary": "Read sandbox catalog headers",
        "description": "Same authentication, query parameters and processing as GET, without a response body.",
        "responses": {
          "200": {
            "description": "Headers for the fixed example catalog; no response body.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or unsupported API version; no response body.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "405": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "Allow": {
                "description": "Allowed HTTP methods.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "500": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "default": {
            "description": "Structured error. See code, message, and hint for recovery.",
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        }
      },
      "options": {
        "operationId": "optionsSandboxGames",
        "summary": "Discover allowed methods and CORS preflight permissions",
        "security": [],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Origin of the requesting browser."
          },
          {
            "name": "Access-Control-Request-Method",
            "in": "header",
            "schema": {
              "type": "string",
              "enum": ["GET", "HEAD"]
            },
            "description": "Method requested by a browser preflight."
          },
          {
            "name": "Access-Control-Request-Headers",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "example": "Content-Type, Authorization",
            "description": "Access-Control-Request-Headers request value."
          }
        ],
        "responses": {
          "204": {
            "description": "Preflight accepted with no response body.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string"
                },
                "example": "GET, HEAD, OPTIONS"
              },
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string",
                  "const": "*"
                }
              },
              "Access-Control-Allow-Methods": {
                "schema": {
                  "type": "string"
                },
                "example": "GET, HEAD, OPTIONS"
              },
              "Access-Control-Allow-Headers": {
                "schema": {
                  "type": "string"
                },
                "example": "Content-Type, Authorization, API-Version"
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Discover allowed methods and CORS preflight permissions. See https://cgs.games/developers for integration guidance."
      },
      "parameters": [
        {
          "name": "API-Version",
          "in": "header",
          "required": false,
          "description": "Major API version. Omit for version 1; any other value returns 400 UNSUPPORTED_API_VERSION. See /developers#versioning.",
          "schema": {
            "type": "string",
            "enum": ["1"],
            "default": "1"
          }
        }
      ]
    },
    "/api/cli/session": {
      "parameters": [
        {
          "name": "API-Version",
          "in": "header",
          "required": false,
          "description": "Major API version. Omit for version 1; any other value returns 400 UNSUPPORTED_API_VERSION. See /developers#versioning.",
          "schema": {
            "type": "string",
            "enum": ["1"],
            "default": "1"
          }
        }
      ],
      "post": {
        "operationId": "verifyCliSession",
        "summary": "Verify the current CLI sign-in",
        "description": "Verifies a Firebase ID token including revocation and returns short-lived session metadata without issuing tokens or changing permissions. Responses are not cached. A creator username is required for publishing, but not for checking the session.",
        "security": [
          {
            "firebaseIdToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Verified session metadata; never includes a token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CliSession"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or unsupported API version.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked Firebase ID token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          },
          "503": {
            "description": "Session information is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        }
      },
      "options": {
        "operationId": "cliSessionOptions",
        "summary": "Discover allowed methods and CORS preflight permissions",
        "security": [],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Origin of the requesting browser."
          },
          {
            "name": "Access-Control-Request-Method",
            "in": "header",
            "schema": {
              "type": "string",
              "enum": ["POST"]
            },
            "description": "Method requested by a browser preflight."
          },
          {
            "name": "Access-Control-Request-Headers",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "example": "Content-Type, Authorization",
            "description": "Access-Control-Request-Headers request value."
          }
        ],
        "responses": {
          "204": {
            "description": "Preflight accepted with no response body.",
            "headers": {
              "Allow": {
                "schema": {
                  "type": "string"
                },
                "example": "POST, OPTIONS"
              },
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string",
                  "const": "*"
                }
              },
              "Access-Control-Allow-Methods": {
                "schema": {
                  "type": "string"
                },
                "example": "POST, OPTIONS"
              },
              "Access-Control-Allow-Headers": {
                "schema": {
                  "type": "string"
                },
                "example": "Content-Type, Authorization, API-Version"
              },
              "API-Version": {
                "description": "Supported major API version.",
                "schema": {
                  "type": "string",
                  "enum": ["1"]
                }
              }
            }
          }
        },
        "description": "Returns POST and OPTIONS with CORS preflight headers for CLI session verification."
      }
    }
  },
  "components": {
    "securitySchemes": {
      "firebaseIdToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Firebase Auth ID token from the signed-in user. Publishing and deletion require a creator username; session verification does not."
      },
      "warmToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Operator GATCG_WARM_TOKEN secret. Only for spoiler cache maintenance; never a Firebase ID token."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error", "code", "message", "hint"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Legacy error message retained for existing clients."
          },
          "code": {
            "type": "string",
            "example": "NOT_FOUND"
          },
          "message": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          }
        }
      },
      "PublishedGame": {
        "type": "object",
        "required": ["success", "slug"],
        "properties": {
          "success": {
            "const": true,
            "type": "boolean"
          },
          "slug": {
            "type": "string"
          }
        }
      },
      "Game": {
        "type": "object",
        "required": [
          "id",
          "username",
          "slug",
          "name",
          "bannerImageUrl",
          "autoUpdateUrl",
          "uploadedAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "slug": {
            "type": "string",
            "description": "URL slug. Public game pages are /{username}/{slug}."
          },
          "name": {
            "type": "string"
          },
          "bannerImageUrl": {
            "type": "string",
            "description": "HTTPS banner URL or site-relative fallback image path."
          },
          "autoUpdateUrl": {
            "type": "string",
            "format": "uri"
          },
          "copyright": {
            "type": "string",
            "description": "Copyright attribution, when present. Some legacy listings omit this field; do not infer ownership from its absence."
          },
          "uploadedAt": {
            "type": "string",
            "format": "date-time"
          },
          "visibility": {
            "type": "string",
            "enum": ["public", "private"],
            "description": "public games are listed in catalogs; private games are unlisted but open to anyone with their page URL. Absent on legacy responses, where it means public."
          }
        }
      },
      "SpoilerCard": {
        "type": "object",
        "required": [
          "uuid",
          "name",
          "card_image_url",
          "back_card_name",
          "back_card_image_url",
          "types",
          "element",
          "effect_raw"
        ],
        "properties": {
          "uuid": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "card_image_url": {
            "type": "string"
          },
          "back_card_name": {
            "type": "string"
          },
          "back_card_image_url": {
            "type": "string"
          },
          "element": {
            "type": "string"
          },
          "effect_raw": {
            "type": "string"
          },
          "types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "JsonValue": {
        "description": "An arbitrary JSON value forwarded unchanged to the upstream service. No CGS domain schema is implied.",
        "anyOf": [
          {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/JsonValue"
            }
          },
          {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonValue"
            }
          },
          {
            "type": "string"
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          },
          {
            "type": "null"
          }
        ]
      },
      "CliSession": {
        "type": "object",
        "additionalProperties": false,
        "required": ["uid", "username", "expiresAt", "storageBucket"],
        "properties": {
          "uid": {
            "type": "string"
          },
          "username": {
            "type": ["string", "null"],
            "description": "Null until a creator username is chosen."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "storageBucket": {
            "type": "string",
            "description": "Firebase Storage bucket used for owned staged uploads."
          }
        }
      },
      "GameVisibilityUpdate": {
        "type": "object",
        "required": ["visibility"],
        "properties": {
          "visibility": {
            "type": "string",
            "enum": ["public", "private"],
            "description": "public lists the game in catalogs; private unlists it while keeping its page open by link."
          }
        }
      },
      "GameVisibilityUpdated": {
        "type": "object",
        "required": ["success", "visibility"],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "visibility": {
            "type": "string",
            "enum": ["public", "private"]
          }
        }
      }
    }
  }
}
