CGS Games developer portal

Use the CGS Games API to discover community Card Game Simulator games or publish and manage games for an authenticated creator. The OpenAPI 3.1 specification describes every endpoint, input, response, and operation ID. Agents should also read llms.txt.

Quickstart: read the game catalog

Public reads need no account or API key. Request version 1 explicitly; the response is a JSON array of up to 100 games, newest first. There are no API pagination or search parameters. Filter the returned array locally and link players to /{username}/{slug}.

curl -H "API-Version: 1" https://cgs.games/api/games

Authentication and API keys

CGS Games does not issue developer API keys. Publishing and deleting require a Firebase Authentication ID token from a signed-in user with a creator username. Sign in on the Upload page to set up your creator profile. In a Firebase client signed into the same project, obtain a fresh token with await auth.currentUser.getIdToken() and send it as Authorization: Bearer <FIREBASE_ID_TOKEN>. A Firebase project API key is not a user credential. Never embed user tokens in public code or URLs.

curl -X POST https://cgs.games/api/games \
  -H "API-Version: 1" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"autoUpdateUrl":"https://example.com/my-game/cgs.json"}'

Replace the example URL with your public HTTPS game specification. This request publishes a real listing; use it only with the creator’s authorization. Expired or invalid tokens return 401. Only the owner can delete a game.

Endpoints

  • GET /api/games: public catalog; GET /api/browse is a compatible alias.
  • POST /api/games: publish a game from an auto-update URL with a Firebase ID token.
  • POST /api/cli/session: verify a Firebase ID token (including revocation) and return its expiry, creator profile and upload bucket. No tokens are issued.
  • POST /api/games/upload: upload a multipart file (.cgs.zip, at most 100 MiB), or submit a JSON stagedPath and originalFilename from an authenticated Firebase Storage upload. See the specification for allowed paths and cleanup behavior.
  • DELETE /api/games/{id}: delete an owned game using its catalog document ID, not its slug. Success is plain text.
  • GET /api/proxy/{url} and POST /api/proxy/{url}: public HTTPS resource passthrough on port 443. Private network targets and unsafe redirects are blocked; active content is sandboxed. Responses are limited to 100 MiB and 30 seconds, and POST bodies to 16 MiB. Responses stream as bytes arrive. If a limit or connection failure occurs after headers have been sent, the stream is aborted; discard partial content. Responses depend on the upstream resource and may be binary. Prefer the typed catalog endpoints for function calls.
  • GET /api/sandbox/games: deterministic example catalog, with no database access.

GET endpoints support HEAD. OPTIONS advertises allowed methods and CORS permissions. Errors include error, code, message, and hint; unsupported methods return 405 with Allow. The proxy cannot guarantee an upstream response schema.

Read-only sandbox

The sandbox catalog returns a fixed sample matching the production Game schema. It does not read or write production data, requires no credentials, and supports GET and HEAD only. Its example URLs and creator are fixtures, not playable listings. It is suitable for testing parsing and UI integration; authenticated writes and uploads are not simulated.

curl -H "API-Version: 1" https://cgs.games/api/sandbox/games

Versioning and deprecation policy

Send the API-Version: 1 request header. Omitting it selects version 1 for existing clients. Responses identify the supported version in API-Version; unsupported requested versions return 400 with code UNSUPPORTED_API_VERSION. This header is documented as a parameter in OpenAPI. Additive optional fields may be introduced within a version; clients should ignore fields they do not recognize. Breaking request or response changes require a new major version.

Before retiring a version, we will publish a migration guide here and provide at least 90 days’ notice. Affected responses will carry a Deprecation structured date (an @-prefixed Unix timestamp), a Sunset HTTP date, and a Link with rel="deprecation" to migration instructions. Version 1 has no scheduled retirement; no deprecation dates are currently emitted.

Rate limits and retries

Catalog reads have no configured application quota. Endpoints with quotas document them in the OpenAPI specification and use the IETF RateLimit draft fields RateLimit-Policy and RateLimit. This is an Internet-Draft, not a finalized RFC. The legacy X-RateLimit headers remain available. Quotas are hints, not a service guarantee.

The r value is the remaining request count; t is seconds until reset. A 429 includes Retry-After in seconds: wait at least that long, then use bounded retries with backoff. Per-client quota responses are not shared-cacheable. CORS exposes version, rate-limit, cache, and retry headers for browser clients.

Official CGS Games CLI

The CLI requires Node.js 22 or newer and prints JSON to standard output. Install the versioned CLI package directly from this site. npm registry publication is pending; the download does not depend on a registry package name.

npm install --global https://cgs.games/downloads/cgs-games-cli-1.0.0.tgz
cgs-games games
cgs-games browse
cgs-games games --sandbox
cgs-games openapi
cgs-games auth login
cgs-games auth status
cgs-games upload --file ./my-game.cgs.zip --dry-run
cgs-games upload --file ./my-game.cgs.zip
cgs-games upload --url https://example.com/my-game/cgs.json
cgs-games auth logout

The browse command is an alias for games and accepts the same options, including --sandbox. Browser login uses Google sign-in and an explicit approval page. The CLI saves an origin-specific Firebase ID token in ~/.cgs-games for up to one hour; sign in again after expiry. Use auth login --no-browser to open the printed link yourself, or auth login --token-stdin for token input. Scripts can supply CGS_TOKEN without saving it. Never pass tokens in command arguments. auth logout removes the saved credential, not environment tokens or browser sessions. Choose a creator username on the Upload page before publishing.

Uploads create real listings using the existing API and Firebase Storage permissions. Archives must be nonempty .cgs.zip files up to 100 MiB. --dry-run checks local inputs without requests; it does not validate ZIP contents or server permissions. No writes are supported in the sandbox. API calls send API-Version: 1 and exit unsuccessfully on an HTTP or network error. Reads time out after 30 seconds; uploads allow five minutes. Check your creator page after a timeout before retrying a publication. The CLI reports Retry-After on 429 without automatically retrying. Use --base-url http://localhost:3000 for local development. For support, visit Contact CGS Games.