# CGS Games

> A community library for sharing and playing custom games with Card Game Simulator (CGS).

Browse games without signing in. Publishing and deleting games require a Firebase ID token and a creator username. Only the owner may delete a game. Game copyright belongs to the credited owner.

Request the homepage with `Accept: text/markdown` for Markdown or `Accept: text/html` for the browser page. Responses vary on Accept. Missing pages return HTTP 404, including a Markdown explanation when requested. API failures return JSON with `error`, `code`, `message`, and `hint` fields.

## API

- [OpenAPI specification](https://cgs.games/openapi.json): Methods, request bodies, authentication, responses, and errors for all API routes.
- [Game catalog](https://cgs.games/api/games): GET returns up to 100 games, newest first. No pagination or search parameters.
- [Legacy catalog](https://cgs.games/api/browse): GET alias for the game catalog.
- [Grand Archive spoilers](https://cgs.games/api/gatcg_spoilers): Cached card data; respect rate limits and Retry-After. Cache maintenance parameters are for operators.

## When to use CGS Games

- [Find a community card game](https://cgs.games/api/games): Use GET with API-Version: 1 to retrieve up to 100 recent games; filter locally by name or creator. Link to /{username}/{slug} using returned fields. Do not invent pagination or assume this is the complete historical catalog.
- [Help a creator publish](https://cgs.games/developers#authentication): Use POST /api/games with an autoUpdateUrl, or POST /api/games/upload for an archive, only after the user authorizes publishing. Authenticate with their Firebase ID token and creator profile. DELETE /api/games/{id} removes an owned listing; get explicit permission before deletion.
- [Read Grand Archive previews](https://cgs.games/api/gatcg_spoilers): Use a normal GET for cached spoiler cards. OCR text may be incomplete. Do not request warm, refresh, or nocache for routine reads. On 429, wait for Retry-After; use RateLimit and RateLimit-Policy to throttle.
- [Test a catalog integration](https://cgs.games/api/sandbox/games): Deterministic, read-only fixtures with the production Game schema. No credentials or production writes. Sample URLs are not playable games.

## Developers

- [CGS Games developer portal and API docs](https://cgs.games/developers): Quickstart, endpoints, authentication, sandbox, CLI, and function-calling guidance. Public reads need no key; the service does not issue developer API keys.
- [Versioning and deprecation policy](https://cgs.games/developers#versioning): API-Version: 1 is explicit or the default. Unsupported versions return 400. Breaking changes require a new major version; retirement requires at least 90 days' notice with Deprecation, Sunset, and a migration link. Version 1 has no scheduled retirement.
- [Official CGS Games CLI](https://cgs.games/developers#cli): games (alias browse) and openapi return public JSON; games and browse accept --sandbox. Use auth login for browser approval or --token-stdin for scripts; CGS_TOKEN can supply a short-lived Firebase ID token. upload --url or --file publishes a real listing only with the creator's authorization; use --dry-run to check inputs without writes. npm registry publication is pending.

## Website

- [Home](https://cgs.games/): Overview and latest games; supports Markdown content negotiation.
- [Browse games](https://cgs.games/browse): Search the game library.
- [Upload](https://cgs.games/upload): Publish an auto-update URL or a .cgs.zip archive, up to 100 MiB.
- [Sitemap](https://cgs.games/sitemap.xml): Public site navigation.
- [Terms](https://cgs.games/terms): Terms of service.
- [Privacy](https://cgs.games/privacy): Privacy policy.
- [About CGS Games](https://cgs.games/about): Card Game Simulator community library operated by Finol Digital LLC.
- [Contact CGS Games](https://cgs.games/contact): Support, privacy and content questions, and the published mailing address.

## Optional

- [Card Game Simulator](https://www.cardgamesimulator.com): The simulator used to play these games.
- [Create a game](https://github.com/finol-digital/Card-Game-Simulator/wiki/Crash-Course-into-Game-Development-with-CGS): Game creation guide.