# Schemas and endpoints

The public URLs on `gamestage.ai`. Everything here answers today, is served
with `access-control-allow-origin: *` where a machine would need it, and is
versionless or explicitly versioned rather than "latest".

## Contracts

| URL | Content type | What it is |
| --- | --- | --- |
| `/schemas/app-manifest/1.0` | `application/schema+json` | The App Manifest JSON Schema, generated from the same models the CLI validates against |
| `/app-spec/<version>/spec.json` | `application/json` | The [Interaction Cloud](https://products.monterosa.co/mic/core-concepts) App Spec for the Gamestage product |
| `/app-spec/<version>/<document>.json` | `application/json` | The documents that spec points at: `elements`, `fields`, `project_settings`, `event_settings` |

The manifest schema resolves with or without a `.json` suffix. An unknown
version is a `404` carrying the versions that do exist, rather than a
redirect to the newest, because a caller asking for a version it was given
should be told plainly that it has gone.

App Spec versions are published, not current: `0.2.0` and `0.3.0` both answer,
and every version that has ever been published keeps answering. A registered
app on the platform holds a `spec_url` naming one version and Studio reads it
every time it draws a producer's screens, so retiring a version would take
every registration on it to a `404`.

## For agents

| URL | Content type | What it is |
| --- | --- | --- |
| `/install` | `text/plain` | The shell installer, for a `gamestage` command on your PATH. No page promotes it: the promoted route is `npx` |
| `/cli` | `text/javascript` | The bundled CLI, one minified file with its licence and its promises in a readable banner at the top |
| `/agent.md` | `text/markdown` | The agent instruction pack the installer writes into a coding agent |
| `/start.md` | `text/markdown` | The agent front door, written to be read once and be enough |
| `/llms.txt` | `text/plain` | The site's map for a model arriving cold |

Every chapter of this documentation is served the same way: add `.md` to any
`/docs/<chapter>` URL for the source Markdown, or `.json` for the same content
in an envelope carrying `doc`, `title` and `markdown`. Chapters that have been
renamed redirect with a `308`, extension and all.

## The player API

The player API is served by the Engine rather than by this site, so its host
is whatever `gamestage dev` printed locally or what `gamestage endpoint <game>
player` reports for a deployed game. Every fan-facing route sits under one
prefix:

```
/play/v1/games/{game}/...
```

That prefix is the boundary. Nothing under it needs a creator credential, and
the Engine serves nothing above it. The routes themselves are in the
[player API reference](/docs/player-api).

## A fan's link

`/play` is the embed URL this product declares in its App Spec. The platform
sends a fan there with the project, CDN host and edition on the query string,
and the route turns the project into the game paired with it, or says plainly
that it cannot. It is the one URL on this host that fans rather than creators
open.

## Not on this host

A deployed game gets its own App Spec, named for the game, and it is served by
Backstage at `/public/v1/games/{id}/app-spec/{version}/{document}` on
`api.gamestage.ai`, not on `gamestage.ai`. That path needs no credential, by
design: it is one of exactly three routes Backstage leaves unauthenticated,
because Studio itself fetches an App Spec document from the URL we registered
and has no way to present a creator's credential. What a deploy does with it
is in [Build and deploy](/docs/migration).