# Ship a game to ShipGames

ShipGames hosts browser games. Each build gets a game page with a Play button, play stats, a devlog and a link to send people.

These are the steps for an AI agent (Claude, ChatGPT, Cursor, Copilot, Gemini or any other) helping a maker ship a game.

Starting a brand-new game? Make its public GitHub repo before the first commit, push as you build, and ship it with ship_github (or POST to https://shipgames.io/api/v1/ship/github). Only games shipped from GitHub, pushed as they were built, can show a Verified build time. The whole start, step by step, is the prompt at https://shipgames.io/ship#start.

## What you need

1. The game: a single HTML file, or a folder with index.html at the top. Static web files only: HTML, JS, CSS, images, sound, fonts, WebAssembly. At most 50 MB and 500 files. No server code.
2. One of these from the maker:
   - The ShipGames connector added to your app (you will see tools named ship_build, list_my_games and so on). Then skip to "With the connector".
   - A ShipGames token (it starts with sgk_). The maker makes one at https://shipgames.io/account and pastes it to you. Never print it back, never put it in a file that gets committed or shared.

If you have neither, ask the maker to add the connector (https://shipgames.io/mcp) or to make a token at https://shipgames.io/account.

## With the connector

1. If this is a new build of a game they already have, call list_my_games and pick the game's slug.
2. Call ship_build with:
   - note: one line on what changed, like "First playable: one level".
   - the game as one of: html (the whole page as text), file_base64 (a .zip of the folder, base64), or file_url (an https link to the .zip or .html).
   - game: the slug, for a new build of an existing game. Leave it out for a new game.
3. Give the maker the page link from the answer.

### From a GitHub repo

Call ship_github with repo (the public repo's link) and path (the built page, default index.html) for a new game, or with game (the slug) for a later build: it ships what was pushed since the last build. Only these games can be Verified.

## With a token

Send the file to the ship API:

    curl -H "Authorization: Bearer $SHIPGAMES_TOKEN" -F file=@game.zip -F note="First playable" https://shipgames.io/api/v1/ship

- A single page works too: -F file=@index.html
- For a new build of an existing game, add: -F game=<slug>
- Or POST JSON: {"html": "<the page>", "note": "..."} with Content-Type: application/json
- Or use the CLI: shipgames login, then shipgames ship <file or folder> -m "note"
- From a public GitHub repo (the only way to get Verified): POST {"repo": "https://github.com/you/your-game", "path": "index.html"} to https://shipgames.io/api/v1/ship/github. Later builds: POST {"game": "<slug>"} there; it ships the new pushes.

The answer is JSON. Give the maker "page" (the game page to send people) and "play" (the build on its own).

## After it ships

- New games start as a private link: only people with the link can play. A maker's very first game is also reviewed before it can be listed.
- To change who can play: set_ring, or POST {"ring": "listed"} to https://shipgames.io/api/v1/games/<slug>/ring. Rings: private, circle (signed-in makers), listed (on the home page), launched.
- To write the devlog: update_devlog, or POST {"title": "...", "body": "..."} to https://shipgames.io/api/v1/games/<slug>/devlog.
- To see how it's doing: get_game_stats, or GET https://shipgames.io/api/v1/games/<slug>.
- 24-hour themes (https://shipgames.io/themes): when one is open, start a new game, ship it, then enter_theme, or POST {"game": "<slug>"} to https://shipgames.io/api/v1/themes/<id>/enter.
- To read what players said: list_feedback (or GET https://shipgames.io/api/v1/feedback), and answer one with reply_feedback. Each comment is tied to a build: what's working, then one thing to try. The maker's Updates inbox: list_updates.

## If it fails

The answer says what to fix, in plain words (for example "No index.html at the top of the game"). Fix it and ship again. 401 means the token is missing or was revoked. 429 means wait a minute.

Full API: https://shipgames.io/docs/api