{"doc":"endpoints","title":"Schemas and endpoints","markdown":"# Schemas and endpoints\n\nThe public URLs on `gamestage.ai`. Everything here answers today, is served\nwith `access-control-allow-origin: *` where a machine would need it, and is\nversionless or explicitly versioned rather than \"latest\".\n\n## Contracts\n\n| URL | Content type | What it is |\n| --- | --- | --- |\n| `/schemas/app-manifest/1.0` | `application/schema+json` | The App Manifest JSON Schema, generated from the same models the CLI validates against |\n| `/app-spec/<version>/spec.json` | `application/json` | The [Interaction Cloud](https://products.monterosa.co/mic/core-concepts) App Spec for the Gamestage product |\n| `/app-spec/<version>/<document>.json` | `application/json` | The documents that spec points at: `elements`, `fields`, `project_settings`, `event_settings` |\n\nThe manifest schema resolves with or without a `.json` suffix. An unknown\nversion is a `404` carrying the versions that do exist, rather than a\nredirect to the newest, because a caller asking for a version it was given\nshould be told plainly that it has gone.\n\nApp Spec versions are published, not current: `0.2.0` and `0.3.0` both answer,\nand every version that has ever been published keeps answering. A registered\napp on the platform holds a `spec_url` naming one version and Studio reads it\nevery time it draws a producer's screens, so retiring a version would take\nevery registration on it to a `404`.\n\n## For agents\n\n| URL | Content type | What it is |\n| --- | --- | --- |\n| `/install` | `text/plain` | The shell installer, for a `gamestage` command on your PATH. No page promotes it: the promoted route is `npx` |\n| `/cli` | `text/javascript` | The bundled CLI, one minified file with its licence and its promises in a readable banner at the top |\n| `/agent.md` | `text/markdown` | The agent instruction pack the installer writes into a coding agent |\n| `/start.md` | `text/markdown` | The agent front door, written to be read once and be enough |\n| `/llms.txt` | `text/plain` | The site's map for a model arriving cold |\n\nEvery chapter of this documentation is served the same way: add `.md` to any\n`/docs/<chapter>` URL for the source Markdown, or `.json` for the same content\nin an envelope carrying `doc`, `title` and `markdown`. Chapters that have been\nrenamed redirect with a `308`, extension and all.\n\n## The player API\n\nThe player API is served by the Engine rather than by this site, so its host\nis whatever `gamestage dev` printed locally or what `gamestage endpoint <game>\nplayer` reports for a deployed game. Every fan-facing route sits under one\nprefix:\n\n```\n/play/v1/games/{game}/...\n```\n\nThat prefix is the boundary. Nothing under it needs a creator credential, and\nthe Engine serves nothing above it. The routes themselves are in the\n[player API reference](/docs/player-api).\n\n## A fan's link\n\n`/play` is the embed URL this product declares in its App Spec. The platform\nsends a fan there with the project, CDN host and edition on the query string,\nand the route turns the project into the game paired with it, or says plainly\nthat it cannot. It is the one URL on this host that fans rather than creators\nopen.\n\n## Not on this host\n\nA deployed game gets its own App Spec, named for the game, and it is served by\nBackstage at `/public/v1/games/{id}/app-spec/{version}/{document}` on\n`api.gamestage.ai`, not on `gamestage.ai`. That path needs no credential, by\ndesign: it is one of exactly three routes Backstage leaves unauthenticated,\nbecause Studio itself fetches an App Spec document from the URL we registered\nand has no way to present a creator's credential. What a deploy does with it\nis in [Build and deploy](/docs/migration).\n"}