# Submit a game to Ant Games

Ant Games (https://antgames.ai) lists free, original browser games. Anyone, including an AI agent, can send one. You send the game's **link** and a few texts, in one JSON request. No account, no login. We never take a game as a file: the game stays on your site and the Play button opens your link.

**Check first whether we are taking games.** `GET https://antgames.ai/api/v1/` answers `door.open`. If it is `true`, send your game. If it is `false`, we take nothing now, and `door.reason` says why. We send no notice when the door opens: look again yourself, once an hour at most.

**Send a game in one request.** `POST https://antgames.ai/api/v1/games` with a JSON body. These fields are required:

- `url`: the https link of the page where the game is played, at most 300 characters.
- `title`: 2 to 40 characters.
- `email`: a real address. Your private link is sent there.
- `description`: 80 to 500 characters, at most 60 words. Say what the player does and what wins.
- `genre`: one of the list under "The fields". Pick the closest; when several fit, any of them is right. It only labels your page: a genre wholly unlike the game on screen can come back as `TEXTS_NOT_TRUE`.
- `howToPlay`: 2 to 5 steps, each 20 to 200 characters, at most 30 words.
- `controls`: 1 to 8 rows of `{ "action": "Jump", "keys": "Space" }`. One row for each action. Two rows may name the same key.
- `accept_terms`: `true`.

`title` is searched on the web: search for it first if you can. `author` is optional: leave it out when there is no name to show. "A whole `meta.json` that passes" below is a body you can copy. Put your own address in `email`: the sample's address is only an example.

With curl, from a file `meta.json` that holds those fields:

```
curl -sS -H 'Content-Type: application/json' --data @meta.json https://antgames.ai/api/v1/games
```

With Node 18 or later (save it as `send.mjs`, then `node send.mjs`):

```js
import { readFileSync } from 'node:fs';
const meta = JSON.parse(readFileSync('meta.json', 'utf8'));
const res = await fetch('https://antgames.ai/api/v1/games', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(meta),
});
console.log(res.status, await res.json());
```

**You get back** `201` with an `id` and a `status_url`. Keep the `id`. No text of the listing may hold a web address or an email address (the link in `url` is the one place for an address).

**What happens next.** We email you a private link at once, to the address in `meta.json`. A program then opens your link and plays your game, and AI reviewers read your texts against what they see. Poll `GET https://antgames.ai/api/v1/games/<id>` until `status` is `live`, `returned` or `rejected`. This usually takes less than a day, sometimes longer. If it is `returned`, `reasons` says what to fix. Every change you send (a new link, new texts, or the same link again) is checked again.

`GET https://antgames.ai/api/v1/` gives the same rules as JSON, and says whether we are taking games now. The rest of this page is reference.

## The request

`POST https://antgames.ai/api/v1/games`, with `Content-Type: application/json`: the fields at the top level of one object. The body is at most 262,144 bytes (256 KiB). Any other content type is answered 415. The whole request must arrive within 30 seconds (otherwise 408 `timeout`).

Bounds on the body: a JSON body is nested at most 12 levels deep and holds at most 5,000 values (every `{`, `[` and `,` outside a string, counted before it is parsed). A listing is a few dozen values. A `multipart/form-data` body is read too, with the one part `meta` that holds the same JSON as text: at most 4 parts, each once. The part `meta` is at most 65,536 bytes. Each part's headers are at most 2,048 bytes.

**We never take a file.** A body that carries one (a part named `game`, or the JSON fields `html` or `html_base64`) is answered `422 invalid`, with this sentence in `problems`:

> Ant Games takes a game by its link, not as a file: put "url" with the https link where the game is played, and send no file

### A whole `meta.json` that passes

```json
{
  "url": "https://lanterndrift.example.org/play/",
  "title": "Lantern Drift",
  "email": "maker@example.org",
  "author": "Mira Okafor",
  "tagline": "Steer a paper lantern up through the night wind.",
  "description": "Keep a paper lantern flying. Hold Space to rise, let go to sink, and grab embers to keep the flame alive. Climb as high as you can before the wind puts you out.",
  "genre": "Arcade",
  "howToPlay": [
    "Press Space or click on the title screen to start.",
    "Hold Space to rise and let go to sink. Steer with the left and right arrow keys.",
    "Touch embers to refill the flame. Dodge the owls. You lose when the flame goes out."
  ],
  "controls": [
    { "action": "Rise", "keys": "Space or hold the mouse button" },
    { "action": "Steer", "keys": "Left and right arrow keys, or A and D" },
    { "action": "Restart after a fall", "keys": "Enter" }
  ],
  "inputs": ["keyboard", "mouse"],
  "session": "Three minutes a run",
  "accept_terms": true
}
```

Use a real address in `email`: its domain must take mail. The sample's own address would be refused, because `example.org` takes no mail. The receipt and the private link are sent there. No text field of the listing may hold a web address, a `www.` name or an email address.

### The answer

`201`:

```json
{
  "id": "k3m5q7a2c4e6g2i4k6m3o5q7s2",
  "status": "queued",
  "status_url": "https://antgames.ai/api/v1/games/k3m5q7a2c4e6g2i4k6m3o5q7s2",
  "manage_url": "https://antgames.ai/submit/manage/#k3m5q7a2c4e6g2i4k6m3o5q7s2",
  "receipt": "pending",
  "message": "..."
}
```

Keep the `id`. The **private link is never in an HTTP answer**: it comes by mail to the address you gave, and nowhere else. `manage_url` is the status page without the key.

### An error is written for you to act on

```json
{ "error": { "code": "invalid", "message": "...", "fix": "...",
             "problems": [ { "field": "description", "message": "must be 80 to 500 characters (it has 12)" } ] } }
```

`422 invalid` lists **every** problem found at once, field by field: fix them all and send again. Other codes: 400 `invalid_json`, `invalid_multipart`, `invalid_body`; 401 `key_required`; 403 `wrong_key`, `cross_site`; 404 `not_found`; 405 `method_not_allowed`; 408 `timeout`; 409 `duplicate_url`, `closed`, `stale_version`; 413 `too_large`; 415 `unsupported_type`; 429 `rate_limited` (with `Retry-After`); 500 `internal`; 503 `door_closed`, `queue_full`, `store_full`, `busy` (each with `Retry-After`).

**What a client does on each refusal.**

- `503 door_closed`: nothing is wrong with the request, and we take no games now. The door stays closed until we open it, so sending again on a timer is refused again. Read `GET https://antgames.ai/api/v1/` (once an hour at most, as `Retry-After` says), and send the same request when `door.open` is `true`.
- `429 rate_limited`, `503 queue_full`, `store_full`, `busy`: the request was fine. Wait the number of seconds in the `Retry-After` header, then send the same request again. (`429` says which limit in `error.limit`. A day limit's `Retry-After` runs to the next UTC midnight. `busy` says 5 seconds.)
- `400`, `401`, `403`, `404`, `405`, `408`, `413`, `415`, `422`, and `409 duplicate_url`: the request must change. Read `error.message`, `error.fix` and, for `422`, every entry of `error.problems`. Do not send the same request again.
- `409 closed`, `stale_version`: the submission takes no change (any more). Follow `error.fix`.
- `500 internal`: the service failed. Try again later.

**A refusal can come before your body is read.** A request refused from its headers (too large, door closed, a limit reached, too many bodies at once) is answered at once. The service then reads and throws away what you are still sending (at most 16 MiB, for at most 15 seconds) before it closes the connection. Read the answer even while you are still sending, and do not treat a closed or reset connection as the answer. `Expect: 100-continue` is honoured: no `100 Continue` comes when the request is refused, so a client that waits for it gets the refusal.

A request with an `Origin` other than `https://antgames.ai`, or a `Sec-Fetch-Site` other than `same-origin` or `none`, is refused 403 `cross_site`: a script in somebody else's web page cannot submit in its visitor's name. A client that is no browser (curl, a script, an agent's HTTP tool) sends neither header and is served.

## The link

`url` is the address a player opens to play. We read it as text first; the rules are the door's own:

- It must be an https:// link. White space, and a link that is not a link, are answered with this sentence.
- It must name a public host name (no IP address, no localhost, no name without a dot).
- It must not be a link to antgames.ai.
- It must carry no user name or password.
- It must use the default port.
- It must be at most 300 characters.
- Surrounding white space is trimmed, and a `#` part at the end is dropped.

**Send the final link**: the page where the game itself opens. A link that sends the player on to another site comes back (`LINK_MOVED`). The same host with or without `www.` is fine.

**One link is one listing.** A link that is already waiting or live as another submission is answered `409 duplicate_url`.

We never take a file. We host nothing of your game: the Play button on its page opens your link in a new tab.

## The fields

Every string is trimmed, normalised (NFC) and one line (no control characters), and holds no web address, `www.` name or email address (`url` is the one field that holds an address). An unknown field is refused by name, so a typing mistake is not swallowed. Lengths count characters. A word is a run of characters between white space.

**How to write the texts.** Visitors read them. Say what the player does, how, and what wins. Put the act first, the story after or not at all. Use everyday words, one thought a sentence, a key or a number and not an adjective ("press Space", "3 lives"). Name only keys that work.

| Field | Required | Rule |
| --- | --- | --- |
| `title` | yes | text, 2 to 40 characters. We search the web for it: a title that is already another game's name is returned |
| `url` | yes | the https link of the page where the game is played, at most 300 characters. See "The link" |
| `email` | yes | a plain local@domain address, at most 254 characters, whose domain takes mail; never shown on the site |
| `description` | yes | text, 80 to 500 characters, at most 60 words |
| `genre` | yes | one of the genres listed below |
| `howToPlay` | yes | list of 2 to 5 strings, each 20 to 200 characters, at most 30 words |
| `controls` | yes | list of 1 to 8 rows `{ "action", "keys" }`, one row for each action, action 2 to 48 characters, keys 1 to 80 characters. Two rows may name the same key. Keys may name the mouse or touch |
| `accept_terms` | yes | exactly `true`: you accept the terms below |
| `author` | no | text, 2 to 60 characters, shown on the game's page. Leave it out when there is no name to show |
| `tagline` | no | text, 8 to 90 characters |
| `tags` | no | list of at most 8 strings, each 2 to 24 characters |
| `features` | no | list of at most 6 strings, each 10 to 90 characters, at most 12 words |
| `inputs` | no | a list from `keyboard`, `mouse`, `gamepad`, `touch`; the default is `["keyboard", "mouse"]` |
| `session` | no | text, 3 to 80 characters, how long a sitting is |
| `zh` | no | a block with the Chinese texts, see below |
| `supersedes` | no | POST only: the id of a queued or returned submission with the same email; that one is closed as superseded |

**Genres** (exactly one, spelt as here): Action, Adventure, Arcade, Artillery, Board & Card, Card, City Builder, Fighting, Idle, Management, Mystery, Pinball, Platformer, Puzzle, Racing, Rhythm, Roguelite, RPG, Runner, Shoot 'em up, Shooter, Simulation, Sports, Stealth, Strategy, Survival, Tactics, Tower Defense.

### The optional `zh` block

Ant Games has Chinese pages. A game that brings its own Chinese texts gets a Chinese page that is indexed. Without the block the Chinese page shows the English texts. Every text must contain at least one Han character, and `controls` (when given) needs as many rows as the English ones.

| Field | Required | Rule |
| --- | --- | --- |
| `title` | no | text, 2 to 40 characters |
| `tagline` | no | text, 8 to 90 characters |
| `description` | yes | text, 30 to 110 characters |
| `howToPlay` | yes | list of 2 to 5 strings, each 8 to 60 characters |
| `controls` | no | list of rows `{ "action", "keys" }`, action 2 to 48 characters, keys 1 to 80 characters |
| `features` | no | list of at most 6 strings, each 4 to 40 characters |
| `session` | no | text, 3 to 80 characters |

## Before you send, check your own game

A game comes back for the reasons in the table below and for no other. Go through this list yourself first:

- It opens at your link for anyone, with no login, and no bot check stands in the way.
- The screen is not blank after ten seconds, and a picture shows within thirty.
- One click, or Space, Enter, Z, X, an arrow key or W A S D, starts it, and the screen answers input.
- A sound plays after the first input.
- The page saves no file on the player's computer (no download), opens no window and asks for no permission by itself. A game may load its own files.
- It starts and keeps running with service workers blocked, as they are in our checker.
- It calls no localhost or private address.
- The link does not send the player on to another site.
- Play is free and sells nothing, asks for no personal data and has a goal, and the game is in English on screen.
- Your texts are true of the game as it is.

## How we check it

A program opens your link in a desktop browser window and plays without knowing the rules: it clicks and presses Space, Enter, Z, X, the arrow keys and W A S D. So a click or one of those keys must start your game. It taps Space, Enter, Z, X and the mouse button. It also holds the arrow keys, W A S D, Space and the mouse button, for a little more than a second at most, and drags the mouse. It presses one key at a time. A game that needs two keys at once, a longer hold or any other key will show little in our play. Our browser blocks service workers: a game that needs one to start, as some engine builds with threads do, does not start in it. A visit also ends when the page loads more than 500 MB in all, uses more than 4 GB of memory, stores more than 1 GB, opens more than 64 connections at once, has headers larger than 64 KB in one request or answer, or does more than we can record. A page that keeps reloading itself or goes past a limit is `returned` with `NOT_CHECKED`. A game that shows nothing in answer is `returned` with `NO_RESPONSE`: mend it and send it again. AI reviewers then judge screenshots of that play against the bar, and compare your texts with what they see. If the screen moves by itself, or changes and then hardly changes again whatever our program presses, our program may not be able to tell an answer from that. The reviewers look for an answer in the screenshots, and a game that shows none is `returned` with `CANNOT_START`. A title that is already the name of another published game, or of a game already on Ant Games, comes back. Your own game at its own link does not count against you.

### The reason codes

A return or a rejection is only ever one or more of these fixed sentences, never free text. A `detail` (a short fact such as the address the page asked for) may be added to the codes of the `vet` rows, on the status only.

| Code | By | Verdict | What it means | Fix |
| --- | --- | --- | --- | --- |
| `LINK_DEAD` | vet | return | The link did not open for our checker: no answer, an error or a bot check. | Send an https link that opens the game for anyone, with no login. If the link opens for you, our checker may not be able to reach your host: put the game on another host. |
| `LINK_MOVED` | vet | return | The link sent the player on to another site. | Send the final link: the one where the game itself opens. |
| `LINK_PRIVATE` | vet | return | The page tried to reach the player's own computer or home network (for example localhost). | Remove every call to localhost or a private address, then send it again. |
| `UNWANTED_ACTS` | vet | return | The page started a download, opened a window or asked for a permission by itself. | Let the game play in its own page and ask for nothing before play. |
| `BLANK` | vet | return | The game's screen was still blank (one flat colour) after ten seconds. | Show a title, a loading bar or the game itself as soon as the page opens. |
| `NO_RESPONSE` | vet | return | Nothing on the screen changed in answer to any click, tap or key. | Start the game from a click or a key on its first screen, and say there which. |
| `NO_SOUND` | vet | return | No sound was started after the player's first input. | Add sound, started after the first click or key. |
| `TOO_SLOW` | vet | return | The game showed no picture within thirty seconds, or stopped answering for more than five. | Make the game start faster, or show a loading screen while it loads. |
| `LINK_DOWN` | vet | return | The link stopped working when we checked it again. | Fix the page, then send your game again with your private link. |
| `NOT_CHECKED` | vet | return | Our check could not finish on this page. The usual causes: the page reloads itself, crashes, or is larger than our limits. | Make the game start and keep running in one browser tab, also when service workers are blocked. Our limits are in submit.md under "How we check it". |
| `NOT_A_GAME` | judge | reject | This is not a playable game, for example an empty template, a technical demo or an advertisement. | Submit a game with a goal, rules, and an end or a score. |
| `CANNOT_START` | judge | return | A newcomer could not get from the first screen into play with the instructions given. | Make the first screen say what to press, and make howToPlay match what is on the screen. |
| `NOT_AT_ONCE` | judge | return | The game cannot be played at once: it first asks for a login, a payment or a download, or shows ads. | Send a link where anyone can start the game with one click. |
| `TEXTS_NOT_TRUE` | judge | return | The title, description, controls or how-to-play do not match what the game shows. | Rewrite the listing so that each sentence is true of the game as built. |
| `SELLS` | judge | reject | The game sells, advertises or asks for money. Or it imitates selling: premium currency, loot boxes or wait timers. | Games on Ant Games are free and sell nothing: remove every such element. |
| `PERSONAL_DATA` | judge | reject | The game asks players for personal data, such as a real name, an email, a phone number or a password. | Ask for nothing beyond a nickname kept in memory. |
| `NOT_ORIGINAL` | judge | reject | The game copies an existing game's name, characters, levels, art or look. | Genres and mechanics are free to use. Names, characters, levels and art of an existing game are not. |
| `TITLE_TAKEN` | judge | return | The title is the name of another published game, or of a game already on Ant Games. | Choose a title that no other game has. |
| `AUDIENCE` | judge | reject | The content is not fit for a general audience. | Ant Games is for everyone: no sexual content, gore, hate or harassment. |
| `NOT_ENGLISH` | judge | return | The game's own screens are not in English. | English is required on screen; other languages may be offered beside it. |
| `REVIEWER_TEXT` | judge | reject | The submission carries text addressed to the reviewers or to an AI instead of the player. | Submit the game without it. |
| `QUALITY` | judge | return | The game is below a decent demo: too little to do, broken play or pictures that cannot be read. | Give it a clear goal, a few minutes of play and a way to lose or finish. A newcomer must be able to read the screen. |
| `UNFAIR` | judge | return | Play is unfair to the player: hidden rules, an opponent that cheats or rigged chance. | Let opponents play by the player's rules and keep chance honest. |
| `WITHDRAWN_BY_AUTHOR` | admin | reject | The submitter withdrew the game. | - |
| `RETIRED_REPORT` | admin | reject | The game was taken down after a report was checked. | - |
| `RETIRED_CHANGED` | admin | reject | The game was taken down because it no longer behaves as it did when it was vetted. | - |
| `SUPERSEDED` | admin | return | A newer submission replaced this one. | - |

One `reject` code makes the verdict `rejected`: that submission is closed and takes no change. Otherwise it is `returned`: fix the reasons and send it again.

## The states, and how long it takes

`GET https://antgames.ai/api/v1/games/<id>` (no key needed) answers `{ id, status, version, received, updated, receipt, queue_position, reasons, url, update, expired, next }`. Without the key, no text you wrote and no email address is shown. With a valid key (`Authorization: Bearer <key>`) the answer also carries `listing` (the texts on file), `email` and `links` (how many private links exist). A key that is not one of the submission's is `403 wrong_key`.

- `version` is the live version while a version is live, otherwise the newest. `received` is when that version arrived. `updated` is when the submission last changed, and is never earlier than `received`.
- `receipt` is `pending` (the email waits to be sent), `sent` or `failed`.
- `queue_position` is a number for a version that waits (`0` while it is being checked) and `null` otherwise, and `null` for a live game.
- `reasons` is filled for `returned` and `rejected` (and for `retired`); each is `{ code, message, fix?, detail? }`.
- `url` is the game's page on Ant Games when live, else `null`. `update` is `{ version, status, queue_position, reasons }` for a newer version of a live game, else `null`.
- `expired` is `true` when the record's files were deleted 14 days after the last decision (see below), else `false`. Then `status` still shows the last state, and `next` says to send the game again as a new submission.
- `next` is a sentence written for an agent about what to do now.

| `status` | What it means |
| --- | --- |
| `queued` | Received; waiting for the check (`queue_position` is its place in line). |
| `vetting` | Being checked and read now. |
| `approved` | Passed; waits for the next publish to the site (a short while). |
| `live` | On the site; `url` is the game's page. A newer version of a live game is reported under `update` while this one stays live. |
| `returned` | Not accepted yet. `reasons` says what to fix. Send it again with `PUT` (or `POST` with `supersedes`). |
| `rejected` | Not accepted, and closed. `reasons` says why. |
| `superseded` | Replaced by a newer version or submission. |
| `withdrawn` | You withdrew it. A live game leaves the site at the next publish. |
| `retired` | Taken down by us; `reasons` says why. |

The check usually takes less than a day, sometimes longer. We cannot promise a time. A mail with the result goes to the address you gave. Poll politely: at most 120 status reads a minute from one client address (after that, `429 rate_limited` says how many seconds to wait). Every few minutes is plenty. Records of returned, rejected, superseded, withdrawn and retired versions are deleted 14 days after the decision. The record then keeps only the id, a hash and dates, and the email is deleted. The private links go with it: your key then gets `403 wrong_key`, and `supersedes` cannot name that id. Send the game again as a new submission.

## Changing a game

Your private link arrives by mail and nowhere else. It is `https://antgames.ai/submit/manage/#<id>.<key>`: open it to change your link or your texts, check the game again or take it down. The key is the part after the dot.

- **By API, with the key.** Send `Authorization: Bearer <key>`:
  - `PUT https://antgames.ai/api/v1/games/<id>`: a new version. The body is JSON with the fields to change: the texts, `url`, or both. What you leave out stays as it is, and a texts-only `PUT` keeps the link on file. A field set to `null` is removed (an optional one). `email` and `supersedes` are not accepted on a `PUT`. A change to a live game queues a new version while the old one stays live; the answer is `202`.
  - `PUT` with the same link as the one on file is taken, and the game is checked again. Use it after you mend a game that came back.
  - A link that is another submission's is `409 duplicate_url`.
  - `DELETE https://antgames.ai/api/v1/games/<id>`: take the game down (it is withdrawn).
  - `DELETE https://antgames.ai/api/v1/games/<id>/links`: cancel every other private link; the one presented stays.
- **Another private link.** `POST https://antgames.ai/api/v1/games/<id>/link` mails another private link to the address on file. The answer is always `202` and the same for a known and an unknown id. Older links keep working.
- **An agent that cannot read the mail** cannot hold a key. Instead, send the corrected game again with `POST` and `"supersedes": "<the id of the earlier submission>"` in the body. It must be a queued or returned submission with the same email, and it is closed as superseded.

## After it is live

The game's page on Ant Games (`url` in the status) shows our own screenshot of your game, your texts and a Play button. The button opens your link in a new tab. The game stays on your site and we host nothing of it. Update the game on your own site whenever you like. We do not review each update. The game must still keep the rules, and we may check it again or take it down at any time.

We open your link again every week to see that the game still opens. If it does not, we try again a day later; if it still does not open, we take the page down and send a mail. The submission is then `returned` with `LINK_DOWN`: mend the page and send `PUT`.

## Limits

Each limit is answered `429 rate_limited` with `Retry-After` (seconds to wait; the same request is fine afterwards). A day is a UTC day. A submission or an update that we refuse does not count toward the day's limits. A status read or a link request counts even when it is refused or the id is unknown.

- 5 submissions a day from one client address (an IPv6 client counts by its /64).
- 3 receipts or links a day to one mail address.
- 10 updates a day to one game.
- 3 link requests a day for one game.
- 100 submissions a day in all, and 200 mails a day in all.
- 120 status reads a minute from one client address (a link request counts as a read too).
- A request is at most 262,144 bytes and must arrive within 30 seconds.
- At most 50 versions wait for a check (`503 queue_full`, `Retry-After` 3600), and the store has a size limit (`503 store_full`).
- At most 6 requests with a body (POST and PUT of a game) are read at once for everybody, and 2 for one client address. The next is answered `503 busy` with `Retry-After: 5`: wait 5 seconds and send it again.
- `GET https://antgames.ai/api/v1/` carries the same numbers as JSON (`limits`).

## Terms

By sending `"accept_terms": true` you state and agree that:

1. You made the game, or have the right to list it.
2. It is original: it copies no existing game's names, characters, levels, art or look.
3. You let Ant Games list your game for free: your texts, your link and our own screenshots of it. We do not host your game. Nobody pays anybody. We may take it down at any time.
4. Your game shows no ads and sells nothing.
5. We use your email address only to write to you about this game, and never show it. We keep the address while a version of your game is live or waiting. When none is, we delete it 14 days later. One thing stays: each time you send, change or withdraw a game, our team gets an email with your address in it. We keep those emails.
6. You can take your game down at any time, with your private link. If the maker of a game tells us we listed it without their word, we take it down.

## Contact

The site is https://antgames.ai. Write to info@antgames.ai.
