API reference

Every route of the platform API, version 1.

https://api.greenmindmedia.com/api/platform/v1

The same API is described for programs as an OpenAPI 3.1 document, at /openapi.json: every route, its credential, its parameters and body as JSON Schema, and the refusals it can answer. Hand it to an HTTP client or a code generator. Versioning says what may change within v1, and the Changelog what has.

Conventions

These hold for every route. Where a route differs, its own section says so.

Credentials

A route takes a server key (gmsk_...), a player's access token, either, or none, sent as Authorization: Bearer <credential>. See Authentication. A route that needs one kind refuses the other with forbidden.

A project's custom dashboard calls with a dashboard token, which names a person rather than a player. It reaches only the routes that let a dashboard in, each needing a permission in the environment that is checked on every call: the custom dashboards routes below, which take nothing else (dashboard in the summary), and GET /config/values, GET /config/tables, GET /config/tables/:key and GET /flags, for whoever may open a dashboard there. Every other route refuses it with forbidden.

Every route acts in the environment its credential belongs to. Only the routes that take no credential name an environment themselves: the EOS sign-in, in its body, and the crash reporter's upload, in its path.

Paths

  • A player's own things are under /players/me. With a player's token, :playerId is always me, and reaches only that player; naming any id, even their own, is forbidden. With a server key, :playerId is a player's id, and a player of another environment is not-found.
  • What belongs to the environment is at the top level: /config, /flags, /legal/documents, /blog, /realms, /definitions, /stats, /sessions, /support, /commerce.
  • The thing acted on is in the path; the body says what to set, or how. A session's seat is /sessions/:sessionId/players/:playerId, an item is /players/:playerId/items/:itemId.
  • An action that is not a read, a write or a delete is a POST with the verb last: /sessions/:sessionId/leave, /players/:playerId/items/:itemId/open, /commerce/grants/:grantId/ack.
  • Sign-ins are under /auth.
  • The one route that names its environment in its path is the crash reporter's, POST /crash-reports/:appKey, since the crash reporter cannot send a credential.
  • Trailing slashes make no difference.

Requests

  • Bodies are JSON, sent with Content-Type: application/json, and strict: a field the route does not take is refused, as is a body that is not JSON. A body is at most 64 KB unless its route says otherwise (16 KB for the sign-ins, the licence routes and the game services, 512 KB for a save, 20 MB for a crash upload); a bigger one is refused with 413 payload-too-large before it is read.
  • Query parameters are strict too: one the route does not take is refused.
  • Strings are trimmed where a route says so, and limits count characters.
  • Ids of players, sessions, items and the like are 1 to 64 characters.
  • Dates are ISO 8601 strings in UTC.
  • Services. A route listed with a service answers service-disabled when the project has not switched it on.
  • Review. Every route that acts for an environment, whatever credential it takes, and the sign-ins and crash uploads that name their environment, answer 403 project-not-approved while the project waits for GreenMind's review, after GreenMind did not approve it, and while GreenMind has it suspended. The public key sets, the OpenAPI document and the licence routes stay open.

Answers

Request Answer
Reads one thing 200 with the thing itself, not wrapped
Reads a list 200 with a page: { "items": [...], "next": "..." or null }
Makes something 201 with what it made; a route that may find instead of make answers 200 when it found
Changes something 200 with it as it now is
Does something, or deletes, and is done 204, with no body. Deleting what is not there is not an error, where the route says so

A list may carry, beside items and next, figures about the whole list: a player's save list says totalBytes, and a list of what one inventory holds says which inventory that was.

Pagination

Every list pages the same way:

Query Rules
limit Optional, 1 to 200; 50 when absent. How many items to answer at most
cursor Optional. The next of the page before; absent for the first page

next is null on the last page. A cursor is opaque: store it and send it back, never build or read one. What it holds differs from list to list and may change; one a list did not make is refused with invalid-request, naming query.cursor. A page can hold fewer than limit items without being the last, so go on until next is null.

The one exception is a change feed, GET /commerce/grants/changes, whose next is never null: it is where to ask from next, and an empty page means you are up to date.

Refusals

Every refusal has one shape:

{
  "error": "invalid-request",
  "message": "body.displayName: Too small: expected string to have >=1 characters",
  "details": { "field": "body.displayName" }
}

error is a code for your program to branch on, from the table under Errors, and never changes meaning. message is a sentence in English for your logs, and may be reworded at any time: what a player sees, word from the code (and details) in their language. details, where there is anything to say, carries the figures behind the refusal:

Field With
field A validation failure: body.<field>, query.<name>, path.<name> or header.<name>
quota, limit quota-exceeded: what the limit counts, and how many are allowed
retryAfterSeconds rate-limited: the same as the Retry-After header
held, requested, allowance, currencyKey, missing, problems The game services' refusals

A path the API does not have answers 404 not-found. A 5xx answer other than 502 and 503 is a fault on our side: retry with backoff.

Rate limits

Each environment's requests are counted against your org's plan, which the console's Usage page shows:

  • Per environment, per minute: every request made with any of the environment's credentials, the EOS sign-in included once its token has been checked.
  • Per credential, per minute: one player's token (and their refreshes), or one server key, so one client cannot use its environment's whole minute.
  • Per environment, per day (UTC).

A request with no credential, or one that is not good (a sign-in, a public key set, a licence call, a crash upload, a mistyped key), is held to limits of its own for the address it came from: 600 a minute across every environment, and for an EOS sign-in 120 a minute in the environment it names. Those count nothing of the environment's, so nobody who knows your app key can use up your minute or your day.

Every answer says where its caller stands against the limit nearest to refusing them:

Header Meaning
X-RateLimit-Limit The most that limit allows in its window
X-RateLimit-Remaining What is left of it after this request
X-RateLimit-Reset Seconds until its window starts again

Minutes are the clock's minutes, not rolling windows. A request over a limit is refused with 429 rate-limited and a Retry-After header, the seconds until the window is over. A refused request is not counted, but retrying at once gets nothing: wait for Retry-After, then back off further if it is refused again. Some routes have limits of their own (support filings, Steam identification, crash uploads); they answer the same way.

Making things past what the plan allows is refused with quota-exceeded, never rate-limited.

Idempotency

A route marked Idempotency-Key takes a header naming the one request, 1 to 128 printable ASCII characters, the same on every retry of it. A retry answers what the first answered and does nothing again; the same key for a different request is refused with idempotency-conflict. Where the key is required, a request without one is refused with invalid-request, naming header.Idempotency-Key. Derive the key from what the request is for (match-8812:reward), never from a clock.

Conditional reads

Config values, config tables, flags and a player's Patreon support answer with an ETag. Send it back as If-None-Match and the answer is 304 Not Modified, with no body, until something changes.

Response shapes

Tokens

interface PlatformTokens {
  accessToken: string
  refreshToken: string
  expiresIn: number // seconds until the access token expires: 3600
  player: PlatformPlayer
}

Player

interface PlatformPlayer {
  id: string
  displayName: string | null
  // Under a GreenMind account somebody has signed in to; always false for your players,
  // who have none (it is GreenMind's own games that put players under accounts)
  linked: boolean
  createdAt: string
}

Patreon support

interface PatreonStatus {
  // The player's GreenMind account has linked Patreon, and your org has connected a campaign
  linked: boolean
  // Entitled today to at least one of your campaign's paid tiers
  supporter: boolean
  supporterSince: string | null // when, as Patreon counts it; null when not a supporter
  // The tiers of your campaign Patreon says they are entitled to today, free ones included
  tiers: { id: string; title: string | null; amountCents: number | null }[]
  showBadge: boolean // whether the account lets other people see a supporter badge
  campaignUrl: string | null // your campaign's Patreon page; null when none is connected
}

Session

interface PlatformSession {
  id: string
  status:
    'CONFIGURING' | 'PREPARING_INSTANCE' | 'AWAITING_PLAYERS' | 'PLAYING' | 'COMPLETE' | 'ERROR'
  gameMode: string
  map: string
  conclusion: string | null
  /** How many players it seats: the project's seats, held to the org's plan */
  seats: number
  players: { playerId: string; playerName: string; isHost: boolean; isReady: boolean }[]
  createdAt: string
}

Realtime

interface PlatformRealtimeInfo {
  /** The sessions socket's address, on the API's own host */
  url: string
  /** The protocol version, `v` in every frame */
  protocol: number
  limits: {
    maxMessageBytes: number
    messagesPerSecond: number
    messagesPerMinute: number
    maxSubscriptions: number
  }
}

Config row

interface ConfigRow {
  key: string
  groupName: string | null
  type: string // 'string' | 'int' | 'float' | 'bool' | 'object' for values made in the console
  valueStr: string | null
  valueInt: number | null
  valueFloat: number | null
  valueBool: boolean | null
  valueJson: { [key: string]: unknown } | null // an 'object' row's JSON object
}

Config table

interface ConfigTable {
  key: string
  name: string
  description: string | null
  groupName: string | null
  columns: {
    key: string
    label: string
    type: string // 'string' | 'int' | 'float' | 'bool' | 'enum' | 'reference' | 'json'
    // Each of these only when it is set; see Config and flags.
    description?: string
    required?: boolean
    default?: string | number | boolean // what a cell left unset reads as
    min?: number
    max?: number
    values?: string[] // an enum column's names
    table?: string // the table a reference column names a row of
    local?: boolean // each environment keeps its own value
  }[]
  // In the editor's order. An empty cell is null or absent. An enum, reference or json cell is a string.
  rows: {
    key: string
    sortOrder: number
    cells: Record<string, string | number | boolean | null>
  }[]
}

Legal document and a player's legal standing

interface LegalDocument {
  document: string // your key for it: 'terms', 'privacy'
  title: string
  url: string // for a hosted document, its page on the publishing site
  version: string // the current version, the one a player accepts
  required: boolean
  hosted: boolean // whether its text is written in the console and hosted by GreenMind
}

interface LegalDocumentText extends LegalDocument {
  // version, title and url are those of the version answered
  body: string // Markdown, as written
  html: string // the same, safe to show as it is
  publishedAt: string
  current: boolean // whether it is the version players are asked to accept now
}

interface LegalStanding {
  documents: (LegalDocument & {
    acceptedVersion: string | null // the latest version the player accepted
    acceptedAt: string | null
    current: boolean // whether they accepted the current version
  })[]
  outstanding: string[] // keys of required documents not accepted at their current version
}

Tour

interface Tour {
  id: string
  name: string
  completed: boolean
  completedAt: string | null
}

Save

interface SaveEntry {
  key: string
  version: number // 1 when first written, one more with every write
  sizeBytes: number
  updatedAt: string
}

interface Save extends SaveEntry {
  data: JsonValue // whatever was written: any JSON value but null
  createdAt: string
}

interface SaveList {
  items: SaveEntry[] // ordered by key
  next: string | null
  totalBytes: number // every slot together, not only this page's
  limitBytes: number // 5,242,880
}

Summary

Method Path Credential Service
GET /openapi.json none
POST /auth/eos none players
POST /auth/refresh none
POST /auth/server server players
GET /.well-known/jwks.json none
GET /apps/:appKey/languages none
GET /players/:playerId either
PATCH /players/:playerId either
DELETE /players/:playerId server
POST /players/:playerId/sign-out either
GET /players/:playerId/patreon either
GET /players/:playerId/platform either
PUT /players/:playerId/crossplay either
PUT /players/:playerId/platform-claims player
PUT /players/:playerId/platform-blocks player
GET /players/:playerId/deletion-request player
POST /players/:playerId/deletion-request player
GET /caller either
POST /identities/lookup server players
POST /admission either
GET /config/values either config
GET /config/tables either config
GET /config/tables/:key either config
GET /flags either flags
GET /.well-known/config-connector-jwks.json none
GET /realtime player sessions
POST /sessions player sessions
GET /sessions/:sessionId either sessions
GET /players/:playerId/sessions either sessions
POST /sessions/:sessionId/join player sessions
POST /sessions/:sessionId/leave player sessions
POST /sessions/:sessionId/ready player sessions
POST /sessions/:sessionId/players/:playerId/kick player sessions
POST /sessions/:sessionId/players/:playerId/promote player sessions
POST /sessions/:sessionId/status either sessions
POST /sessions/:sessionId/events either sessions
POST /maps/:mapKey/versions server
GET /media/:collection either
GET /legal/documents either legal
GET /legal/documents/:document either legal
GET /players/:playerId/legal either legal
GET /players/:playerId/legal/outstanding either legal
POST /players/:playerId/legal/accept player legal
GET /players/:playerId/tours player tours
POST /players/:playerId/tours/:tourId/complete player tours
GET /blog/posts either blog
GET /blog/posts/:slug either blog
GET /blog/categories either blog
GET /blog/tags either blog
POST /support/requests player support
POST /support/reports player support
GET /players/:playerId/data either persistence
GET /players/:playerId/data/:key either persistence
PUT /players/:playerId/data/:key either persistence
DELETE /players/:playerId/data/:key either persistence
POST /crash-reports/:appKey none crashes
POST /crash-symbols/uploads server crashes
GET /crash-symbols/files server crashes
GET /commerce/catalog player commerce
POST /commerce/orders player commerce
POST /commerce/steam/identify player commerce
POST /commerce/steam/authorizations player commerce
POST /commerce/orders/reconcile player commerce
GET /players/:playerId/entitlements either commerce
GET /commerce/grants server commerce
GET /commerce/grants/changes server commerce
POST /commerce/grants/:grantId/ack server commerce
POST /auth/dashboard none
GET /dashboard/session dashboard
GET /players dashboard players
GET /licence/jwks.json none
POST /licence/activate licence key
POST /licence/check licence key
POST /licence/release licence key

The Players service is always on, so the routes without a listed service need nothing switched on. The licence routes belong to no environment: they are for the GmCommon plugin, with the org's licence key as the credential, and are described in GmCommon. The commerce routes' flow is described in Commerce.

The game services' routes, described under Game services below:

Method Path Credential Service
GET /realms either realms
GET /realms/current either realms
GET /definitions/realms server realms
GET /definitions/currencies server inventory
GET /definitions/item-types server inventory
GET /definitions/card-types server cards
GET /definitions/card-templates server cards
GET /definitions/skill-trees server progression
GET /players/:playerId/inventories either inventory
GET /players/:playerId/inventories/:inventory either inventory
GET /players/:playerId/inventories/:inventory/balances either inventory
GET /players/:playerId/inventories/:inventory/items either inventory
GET /players/:playerId/inventories/:inventory/item-stacks either inventory
GET /players/:playerId/ledger either inventory
POST /players/:playerId/purchases/items either inventory
POST /players/:playerId/items/:itemId/use either inventory
POST /players/:playerId/item-stacks/use either inventory
POST /players/:playerId/items/:itemId/open either inventory
POST /players/:playerId/currencies/:currencyKey/credit server inventory
POST /players/:playerId/currencies/:currencyKey/debit server inventory
POST /players/:playerId/currencies/:currencyKey/refund server inventory
POST /players/:playerId/currencies/:currencyKey/consume server inventory
POST /players/:playerId/items/grant server inventory
POST /players/:playerId/items/:itemId/consume server inventory
POST /players/:playerId/item-stacks/consume server inventory
GET /players/:playerId/inventories/:inventory/cards either cards
GET /players/:playerId/inventories/:inventory/card-stacks either cards
POST /players/:playerId/purchases/cards either cards
GET /players/:playerId/decks either cards
POST /players/:playerId/decks either cards
GET /players/:playerId/decks/:deckId either cards
PATCH /players/:playerId/decks/:deckId either cards
DELETE /players/:playerId/decks/:deckId either cards
PUT /players/:playerId/decks/:deckId/cards/:cardId either cards
DELETE /players/:playerId/decks/:deckId/cards/:cardId either cards
PUT /players/:playerId/decks/:deckId/types/:cardTypeKey either cards
GET /players/:playerId/decks/:deckId/validation either cards
POST /players/:playerId/cards/grant server cards
POST /players/:playerId/cards/:cardId/consume server cards
POST /players/:playerId/card-stacks/grant server cards
POST /players/:playerId/card-stacks/consume server cards
GET /players/:playerId/xp either progression
POST /players/:playerId/xp server progression
GET /players/:playerId/skill-trees either progression
GET /players/:playerId/skill-trees/:treeKey either progression
POST /players/:playerId/skill-nodes/:nodeKey/unlock either progression
GET /players/:playerId/unlocks either progression
PUT /players/:playerId/unlocks/:key server progression
DELETE /players/:playerId/unlocks/:key server progression
GET /players/:playerId/stats either stats
GET /stats either stats
POST /players/:playerId/stats/:key/increment server stats
POST /stats/:key/increment server stats
POST /actions/:action either
POST /events/:event either
POST /collections/:collection/query either
POST /collections/:collection/write either
POST /reads either
POST /ext/definitions/check publish key or person
POST /ext/definitions/push publish key or person
POST /ext/definitions/flows/switch publish key or person
POST /ext/definitions/config-defaults publish key or person
GET /ext/environments person
GET /ext/environments/:appKey/status publish key or person
GET /ext/environments/:appKey/server-keys person
POST /ext/environments/:appKey/server-keys person
DELETE /ext/environments/:appKey/server-keys/:keyId person
GET /ext/environments/:appKey/publish-keys person
POST /ext/environments/:appKey/publish-keys person
DELETE /ext/environments/:appKey/publish-keys/:keyId person
GET /ext/environments/:appKey/function-runtime person
PUT /ext/environments/:appKey/function-runtime person
GET /ext/environments/:appKey/collection-storage person
PUT /ext/environments/:appKey/collection-storage person
POST /ext/environments/:appKey/connections/:connection/check person
GET /ext/tool none
POST /ext/functions/upload publish key or person
POST /ext/webhooks/:appKey/:connection none
POST /ext/webhooks/:appKey/:connection/:token none
GET /.well-known/ext-endpoint-jwks.json none

Sign-in

POST /auth/eos

Signs a player in with an Epic Online Services id token, in an environment that accepts EOS. No credential.

Field Type Rules
appKey string Required, 1 to 64 characters. The environment's app key
idToken string Required, 1 to 8,000 characters. The EOS Connect id token of the player's product user
greenMindIdToken string Optional, 1 to 6,000 characters. The player's GreenMind ID token, issued to one of this project's game clients at most ten minutes ago: links the player

Answers Tokens: 201 when the sign-in made the player (the first time their product user id is seen), 200 after that. With greenMindIdToken, the player is linked to the GreenMind account it names; without it they sign in as whoever they already are. The link is made only when idToken is the EOS token of a sign-in made with that GreenMind token through GreenMind's OpenID provider; any other EOS sign-in sent with greenMindIdToken is refused.

Refusals: provider-disabled when EOS is not switched on for the environment; unauthorized when the EOS token cannot be verified or is for another deployment, or the GreenMind token fails a check (another project's client, not a game client, expired, too old, an EOS sign-in that did not go through GreenMind's OpenID provider, or one naming another account than the token); forbidden when the GreenMind account is closed; conflict when the player is another account's, the account has another player here, or the GreenMind token was already used for another player; service-disabled when no environment has that app key; quota-exceeded for a new player past the plan.

POST /auth/refresh

A new pair of tokens for a refresh token. No credential.

Field Type Rules
refreshToken string Required, 1 to 4,000 characters

Answers 200 with Tokens. Refusals: unauthorized when the refresh token is invalid or expired, its player no longer exists, or the player has been signed out everywhere since it was issued.

POST /auth/server

Your server vouches for a player by your own id for them. Server key.

Field Type Rules
subject string Required, 1 to 200 characters. Your id for the player
displayName string Optional, 1 to 40 characters after trimming. Replaces the player's name when given

Answers Tokens: 201 when the sign-in made the player, 200 when it found them. Refusals: quota-exceeded for a new player past the plan.

GET /.well-known/jwks.json

The public keys player tokens are signed with, as a JSON Web Key Set. No credential. Your server uses it to check a player's token itself; see Authentication.

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo",
      "kid": "kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k",
      "alg": "EdDSA",
      "use": "sig"
    }
  ]
}

While a key is being replaced the set holds two: the new one first, and the old one until the last token it signed has expired. Cache the set, and fetch it again when a token names a kid you do not have.

Languages

GET /apps/:appKey/languages

The languages an environment offers its players: those the platform has on and the environment has switched on in the console, English first. No credential, so a game's language picker can read it before anybody signs in. Cached for a minute.

Answers 200 with { languages: [{ code, nativeName, englishName }] }. code is what to send as Accept-Language: every route then answers in that language, falling back to English for anything not yet translated, and says which it chose in Content-Language. Refusals: not-found when no environment has that app key.

Players

GET /players/:playerId

One player. Answers 200 with Player, or not-found. With a player's token, GET /players/me is also the way for your server to check a token a client gives it: the token is good if this answers.

PATCH /players/:playerId

Changes a player's display name.

Field Type Rules
displayName string Required, 1 to 40 characters after trimming

The name passes a word filter for names, which stars out words it does not allow. Answers 200 with Player, showing the name as stored.

DELETE /players/:playerId

Deletes a player at their request. Server key. Their display name, identities, saves, tours, seats, game state and what they hold from purchases go, and every token they hold stops working; the same id signing in again is a new player. Answers 204, or not-found.

POST /players/:playerId/sign-out

Signs a player out everywhere: every token they hold, access and refresh alike, stops working within moments. me with a player's token, a player's id with a server key. Nothing they own or saved is touched. Answers 204, or not-found.

GET /players/:playerId/patreon

Whether the player supports your org on Patreon, as PatreonStatus. Your org connects its campaign on its Patreon page in the console; a player links Patreon to their GreenMind account once, on greenmindmedia.com, so a player with no GreenMind account is never linked. Free tiers are listed in tiers but do not make a supporter. Show a badge beside somebody else only when showBadge is true; a perk the player gets for themselves need not ask. Answers with an ETag (see Conditional reads). See Patreon supporters.

Your backend

For a backend of your own that serves routes of its own to your game, holding nothing of the platform's but your server keys.

GET /caller

Who the credential is. A server key answers { appKey, kind: 'server', keyId } and a player's token { appKey, kind: 'player', playerId }: the way your backend checks a key one of your game servers sent it, or a token a client sent. A credential that is not good (revoked, expired, signed out everywhere) is 401, as on every route.

POST /identities/lookup

Your environment's players paired with the accounts of one sign-in provider. Server key. Send { provider, subjects } (the provider's account ids, such as EOS product user ids) or { provider, playerIds }, at most 100, and get back { identities: [{ playerId, provider, subject }] } for those that have a pair, in no particular order. For a backend that knows its players by their provider account. An account id is never shown to other players, so no player's token may ask.

POST /admission

Holds a request to your own backend to the platform's limits. Send it with the credential that request came with, before your backend does the work, and { service } naming the service the route belongs to, or {}. It is counted against your plan's rate limits and your usage as any platform request is, and refused as one would be: 429 rate-limited with Retry-After, 403 project-not-approved, or 403 service-disabled while your project has that service switched off. Answers 200 with the rate limit headers and { admission, calls, expiresInSeconds }. Send admission as the GM-Admission header on the calls your backend makes to the platform for that same request, with the same credential, and they are not counted again: the request counts once, however many calls it makes (at most calls, within expiresInSeconds; past either a call is counted as any other, and every call is still checked and refused as usual). admission is null when the platform could not keep one. A route of yours that already calls the platform need not ask: that call is admitted itself.

Your server socket is told when the environment's flags, config values or config tables change (a notice frame named config.changed), so a backend that keeps a copy of them can drop it at once and still keep one between changes.

Config and flags

Each of these answers with an ETag, and 304 to an If-None-Match naming it, until something changes. See Config and flags.

GET /config/values

The environment's config values, ordered by key, a page at a time. Either credential. Service: config.

Query Rules
groupName Optional, 1 to 120 characters. Only values in that group

Answers 200 with a list of ConfigRow.

GET /config/tables

The environment's config tables, ordered by key, each with its columns and rows, a page at a time. Either credential. Service: config. Answers 200 with a list of ConfigTable.

GET /config/tables/:key

One config table by its key. Either credential. Service: config. Answers 200 with ConfigTable, or not-found.

GET /flags

The environment's feature flags, ordered by name, a page at a time. Either credential. Service: flags. Answers 200 with a list of { "name": string, "isEnabled": boolean }.

GET /.well-known/config-connector-jwks.json

The public keys the platform signs its requests to your config connector with, as a JSON Web Key Set ({ keys }, Ed25519, alg EdDSA). No credential. They are not the keys player tokens are signed with. Your backend checks each request's bearer token against them: issuer gm-platform, audience your connector's own address, type config-connector. Answers with an ETag and Cache-Control: public, max-age=300.

Sessions

Every sessions route needs the sessions service. See Sessions for the lifecycle, and Realtime for the socket that tells every seat what changed.

GET /realtime

Where the player's client opens the sessions socket, and the limits it is held to there. Player token. Answers 200 with Realtime. Read it when your game starts rather than building the address in: it may move, and the limits follow your org's plan.

POST /sessions

Opens a lobby with the caller seated as host. Player token.

Field Type Rules
gameMode string Required, 1 to 60 characters after trimming
map string Required, 1 to 60 characters after trimming
playerName string Optional, 1 to 40 characters after trimming. The seat's name; defaults to the player's display name, or Player
uniqueNetId string Optional, up to 200 characters. Stored with the seat, not returned

Answers 201 with Session, status CONFIGURING.

GET /sessions/:sessionId

Reads a session. Either credential. Answers 200 with Session, or not-found.

GET /players/:playerId/sessions

The environment's sessions a seat was taken in under playerId, the seat taken most recently first, a page at a time: for a match history, or what your game counts over a player's last matches. Either credential: a server key may name any seat's id in its environment, a player only their own (else forbidden). Service: sessions.

Query Rules
ended Optional, true for only the sessions that started and were reported complete with a conclusion

Answers 200 with a list of Session, each with completedAt (null until it completed).

POST /sessions/:sessionId/join

Seats the caller. Player token.

Field Type Rules
playerName string Optional, as for POST /sessions
uniqueNetId string Optional, as for POST /sessions

Send {} when giving neither. Answers 200 with Session. Refusals: not-found for no such session; conflict when the session is full (its seats, with details.limit), the caller is already seated, or the session is past CONFIGURING.

POST /sessions/:sessionId/leave

Gives up the caller's seat, in any status. Player token. Any body is ignored. Answers 204. Refusals: not-found when the session does not exist or the caller is not seated. The host role is not passed on.

POST /sessions/:sessionId/ready

Player token.

Field Type Rules
isReady boolean Required

Answers 200 with Session. When the caller readies and every other seated player is ready, the status in the answer is PREPARING_INSTANCE. Refusals: not-found when the session does not exist or the caller is not seated; conflict when the session is past CONFIGURING.

POST /sessions/:sessionId/players/:playerId/kick

The host removes a seated player. Player token. Answers 200 with Session. Refusals: not-found when the session does not exist or the caller is not seated; forbidden when the caller is not the host; conflict when the player is not seated or the session is past CONFIGURING.

POST /sessions/:sessionId/players/:playerId/promote

The host makes another seated player host. Player token. Answers 200 with Session. Refusals as for kick.

POST /sessions/:sessionId/status

Your server reports the match's progress with its server key, or, for a match that runs on a player's machine, the player hosting the session with their own token (any other player is forbidden). Players' reports are taken only once the environment's config value sessions.hostReports (a bool) is on; it is off unless you switch it on, and until then any player's report is forbidden. A report from a player's machine is untrusted: a flow that pays out on it is held to its per-player limit.

Field Type Rules
status string Required: AWAITING_PLAYERS, PLAYING, COMPLETE or ERROR
conclusion string Optional, 1 to 60 characters after trimming. Kept with COMPLETE
error string Optional, up to 500 characters. Kept with ERROR
report JSON Optional, up to 16 KB: your game's own account of the match, handed to its session.before_complete flow

Allowed moves: PREPARING_INSTANCE to AWAITING_PLAYERS, PLAYING or ERROR; AWAITING_PLAYERS to PLAYING or ERROR; PLAYING to COMPLETE or ERROR. Answers 200 with Session. Refusals: not-found; conflict for any other move, or when another report changed the session first.

POST /sessions/:sessionId/events

What happened during the match, and where: deaths, for now. The console's Monitoring section counts them, and draws those with a location on its heat map over your map's picture (see POST /maps/:mapKey/versions). Server key, for any seat of the session; or player token, for the player's own seat, or any seat while they host the session.

The body is { events: [...] }, 1 to 100 events. Each event:

Field Type Rules
kind string Required: death
playerId string Required: the seat it happened to, as the session names its players
occurredAt string Optional ISO 8601 moment, during the session and at most 7 days ago. When it arrives if absent
map string Optional, up to 128 characters. The session's own map if absent
mapVersion string Optional: the version of the map's picture this build was made with
location object Optional { x, y, z }, in your game's world units
cause string Optional, up to 128 characters: what did it, as your game names it (FALL_DAMAGE)
killer string Optional, up to 128 characters: who or what, finer than the cause (a monster's class)
runSeconds integer Optional, 0 to 86400: how far into the match
build string Optional, up to 128 characters
platform string Optional, up to 128 characters

Answers 200 with { recorded }. Counted against the plan's session events per day; a report that would pass it is refused whole with rate-limited. Refusals: not-found for a session that is not there or a player not seated in it; forbidden for a player who is not the host reporting another seat; invalid-request for a seat not in the session or a time outside it.

Maps

POST /maps/:mapKey/versions

A picture of one of the project's maps, which the console draws its heat map over. Server key, of any of the project's environments: a picture is the project's, so Test and production draw over the same ones. Upload it from the build machine or editor that draws the map, every time it does; the same bytes again change nothing but the placement.

The body is the picture itself (PNG, JPEG, WebP, GIF or AVIF, at most 25 MB and 16384 pixels on a side), sent with its own Content-Type. :mapKey is the map as your sessions and events name it: letters, digits, dots, hyphens and underscores. The query says which picture it is and where the world sits on it:

Query Type Rules
version string Required: your name for this picture, which events send as mapVersion
name string Optional: the map's name as the console shows it
left number Required: the world's x at the picture's left edge
right number Required: the world's x at its right edge
top number Required: the world's y at its top edge
bottom number Required: the world's y at its bottom edge
swapAxes boolean Optional, true or false: the world's y runs across the picture instead
aliases string Optional: other names your game files this map under, comma separated, up to 20

aliases is for a map whose sessions or events name it differently from its picture: a session's map name where the picture is keyed by the level, say. Events under any of them are drawn over this map's pictures and counted as this map. An upload adds the names it sends to the ones the map already has; the console's Maps page edits and removes them. A name is one map's only.

A reversed axis is a reversed pair: a picture whose right edge is the world's smaller x has left greater than right. Answers 200 with PlatformMapVersion: { mapKey, name, version, width, height, bytes, sha256, placement, createdAt }. Refusals: invalid-request for a file that is not a picture or is too large on a side, or an alias that is the map's own key; payload-too-large; quota-exceeded past the plan's map pictures per project; and conflict when :mapKey or an alias is already another map's name.

Media

GET /media/:collection

A public media collection, for your sites to render: a gallery of screenshots, a list of trailers, edited once in the library they belong to (the project's own, or that of the brand marketing the game in GreenMind Marketing). Player token or server key. :collection is the collection's id, shown on its page once it is public.

Answers 200 with { id, name, description, items }, the items in the collection's order, each { assetId, versionId, kind, title, alt, url, contentType, bytes, width, height, durationSeconds }. kind is image, video or other; url is a permanent public address. Only approved files that are neither a spoiler nor under embargo are listed, so a file appears once it is approved and its embargo ends, and goes when it is turned down or marked a spoiler. Answers with an ETag and Cache-Control: public, max-age=300; send the tag back as If-None-Match to be answered 304 until something changes. Refusals: not-found for a collection that is not public, or not the project's or a project linked to it in the same org.

Every legal route needs the legal service. See Other services for how a game uses them.

Every legal document of the environment, ordered by key. Either credential. Answers 200 with a list of LegalDocument.

The text of a document written in the console and hosted by GreenMind (hosted is true): its current version, or the one the optional version query parameter names, such as the version a player accepted. Either credential. Answers 200 with LegalDocumentText. html is the Markdown in body already made safe to show as it is: HTML written in the Markdown comes out as text, links go only to https, http, mailto and anchors on the page, and images are left out. Refusals: not-found for an unknown document or version, and for a document whose text is on your own site when no version is named.

Where one player stands. Answers 200 with LegalStanding, or not-found.

The required documents whose current version the player has not accepted. Answers 200 with a list of LegalDocument; an empty list means the player may play.

POST /players/:playerId/legal/accept

Records the signed-in player's acceptance of the versions they were shown. Player token, so :playerId is me.

Field Type Rules
documents array Required, 1 to 20 of { "document": string, "version": string }, each the key and current version of one document

Answers 200 with LegalStanding. Accepting a version already accepted changes nothing. Refusals: invalid-request when a document does not exist, or a version is not its current one.

Tours

Every tour route needs the tours service, and a player's token: :playerId is me.

GET /players/:playerId/tours

The environment's switched-on tours, ordered by name, with whether the player has finished each. Answers 200 with a list of Tour.

POST /players/:playerId/tours/:tourId/complete

Marks a tour finished for the player. Any body is ignored. Answers 204, again if it was finished already. Refusals: not-found for a tour that is not the environment's.

Blog

Every blog route needs the blog service, and reads published posts only: a draft, or a post scheduled for later, is not-found until it is published. Post shapes are those the console's blog pages write: a summary carries slug, title, subtitle, excerpt, publishedAt, readingMinutes, featured, authorName, category, tags and cover; a full post adds content (the post's document, as JSON), seoTitle, seoDescription and updatedAt.

GET /blog/posts

Published posts, newest first, a page at a time. Either credential. A page reads on from the last post of the page before, so a post published while you read moves nothing you have yet to reach.

Query Rules
category Optional. A category's slug: only its posts
tag Optional. A tag's slug: only posts with it

Answers 200 with a list of post summaries. Refusals: not-found for a category or tag that does not exist.

GET /blog/posts/:slug

One published post. Either credential. Answers 200 with { "post": Post, "related": PostSummary[] }, where related is more to read, from the same category first. Refusals: not-found.

GET /blog/categories

The categories with at least one published post, in the order set in the console. Either credential. Answers 200 with a list of { "slug", "name", "description" }.

GET /blog/tags

The tags on at least one published post, ordered by name. Either credential. Answers 200 with a list of { "slug", "name" }.

Support

Every support route needs the support service, and a player's token. A player can file ten requests and reports an hour between them; the next is refused with 429 rate-limited, and Retry-After says how many seconds until the hour is over.

POST /support/requests

Files a support request for the signed-in player in the environment's inbox.

Field Type Rules
subject string Required, 3 to 120 characters after trimming
message string Required, 10 to 5,000 characters after trimming
contactEmail string Optional, an email address, up to 254 characters. Where staff can answer

Answers 201 with { "id" }, the request in the inbox.

POST /support/reports

The signed-in player reports another player of the environment.

Field Type Rules
playerId string Required, 1 to 64 characters. The player reported
reason string Required, 2 to 60 characters after trimming. Your own word: cheating, name
details string Optional, up to 2,000 characters after trimming. What the reporter wrote

Answers 201 with { "id" }. Refusals: not-found for a player who is not the environment's; invalid-request for a player reporting themselves.

Player saves

Every save route needs the persistence service. A key is 1 to 120 letters, digits and . _ : -. A slot whose key starts server: is written only with a server key; a player's token reads it, and is refused with forbidden if it writes or deletes it. See Player saves.

GET /players/:playerId/data

The player's slots, ordered by key, without their values. Answers 200 with SaveList, or not-found for a player who is not the environment's.

GET /players/:playerId/data/:key

One slot. Answers 200 with Save, or not-found for a slot never written.

PUT /players/:playerId/data/:key

Writes one slot, making it if it is new.

Field Type Rules
data JSON Required. Any JSON value but null, up to 256 KB written compactly
expectedVersion integer Optional, 0 or more. Write only if the slot is at this version now; 0 for a slot that must not exist. Absent, always write

Answers SaveEntry, carrying the new version: 201 when the write made the slot, 200 when it replaced it. Refusals: conflict when the slot is not at expectedVersion; quota-exceeded when the player's saves would pass 5 MB (details.quota playerDataBytesPerPlayer) or the environment's would pass its plan (playerDataBytes); invalid-request for a value over 256 KB, null, or a malformed key; 413 payload-too-large for a body over 512 KB.

DELETE /players/:playerId/data/:key

Empties a slot. Answers 204, whether or not it held anything.

Crash reports

POST /crash-reports/:appKey

No credential; service crashes. Where Unreal's crash reporter uploads, named as its DataRouterUrl: the body is the compressed crash as the reporter sends it, and the query parameters are the ones the reporter adds (AppID, AppVersion, AppEnvironment, UploadType, UserID). Answers 200 with { "received": true } as soon as the upload is kept; it is read into the environment's crashes moments later. Refusals: 413 payload-too-large over 20 MB; invalid-request for an empty body; 429 rate-limited, with Retry-After, when one address has sent more than 10 to the environment in ten minutes, or everybody together more than 600 in an hour; service-disabled for an environment that has not switched crash reports on or does not exist; 503 unavailable where crash reports cannot be collected. See Crash reports.

POST /crash-symbols/uploads

Server key; service crashes. An upload URL for one of a build's debug files, so its crashes' pages can name the files that resolve their offsets. See Crash reports.

Field Type Rules
label string The build's Symbols, as its crash reports show it. Letters, digits and * + . _ -, up to 200
version string The build's GmProjectVersion. Letters, digits and + . _ -, up to 64
fileName string The file's own name, no folders. Letters, digits and + . _ -, up to 200
sizeBytes number The file's exact size, up to 4 GB
sha256 string The file's SHA-256, 64 lower-case hex digits

Answers 200 with { url, headers, key, expiresAt }: PUT the file to url with exactly headers before expiresAt (an hour). S3 refuses a body of another size or digest. No part may contain ... Refusals: 503 unavailable where symbols cannot be published.

GET /crash-symbols/files

Server key; service crashes. The symbol files the environment has published, by label, then version, then name, a page at a time, narrowed by the optional query parameters label and version. Answers 200 with a list of { label, version, name, sizeBytes, updatedAt }. Refusals: 503 unavailable where symbols cannot be published.

Custom dashboards

How a project's custom dashboard signs its people in, and what it reads that a game does not.

POST /auth/dashboard

No credential. Signs a person in to the dashboard of an environment's project with the code GreenMind sent back to the dashboard's /auth/callback.

Field Type Rules
appKey string Required, 1 to 64 characters. The environment to sign in to, one of the project's
code string Required, up to 2,048 characters. The code the callback was given
codeVerifier string Required, 43 to 128 characters of A-Z a-z 0-9 . _ ~ -. The PKCE verifier of the sign-in
nonce string Required, 16 to 256 characters. The nonce the sign-in was started with

Answers 200 with { accessToken, expiresIn, appKey, permissions }: the dashboard token, the seconds until it runs out (3600), the environment, and what the person may do there. Refusals: not-found where the environment's project has no dashboard; 401 unauthorized where the code is not good, has been used, or answers another sign-in; forbidden for somebody who may not open a dashboard in the environment, or whose GreenMind account is closed; 503 unavailable where this deployment hosts no custom dashboards.

GET /dashboard/session

Dashboard token. Who the token is for and what they may do in its environment, asked of the permission engine now. Answers 200 with { appKey, account: { id }, permissions }.

GET /players

Dashboard token, for somebody who may view players. The environment's players, newest first, a page at a time, narrowed by the optional query parameter q (part of a display name, or a player's id or an identity's subject exactly; never an email). Answers 200 with a list of { id, displayName, identities, hasGreenMindAccount, createdAt, lastSeenAt }.

Commerce

Every commerce route needs the commerce service. The flow, the grants a product can give and what each refusal means are in Commerce.

Route Credential Body or query Answers
GET /commerce/catalog player ?provider=steam { products }, priced for the player
POST /commerce/orders player { sku, provider, locale }; Idempotency-Key, optional 201 with the order
POST /commerce/steam/identify player { ticket, identity: "gm-commerce" } { steamId }
POST /commerce/steam/authorizations player { steamOrderId, authorized } { order, entitlements }
POST /commerce/orders/reconcile player none { orders, entitlements }
GET /players/:playerId/entitlements either the page's A list of entitlements
GET /commerce/grants server the page's A list of grants not yet acknowledged
GET /commerce/grants/changes server the page's A list of changes; next is never null
POST /commerce/grants/:grantId/ack server none The grant, acknowledged

POST /commerce/steam/identify is limited to ten calls a player in ten minutes, each of which asks Steam; the next is refused with rate-limited.

Game services

Services realms, inventory, cards, progression and stats, as each route's table row says. See Game services for what each thing is. A player's token gets forbidden from every route marked server, whatever it sends.

Keys (of currencies, item types, card types, templates, trees, nodes, unlocks and stats, and reason) are 1 to 128 letters, digits and . _ : -, starting with a letter or digit. Ids are 1 to 64 characters. Amounts are whole numbers from 1 to 1,000,000,000; quantities from 1 to 1,000. A body is at most 16 KB.

Choosing an inventory. A path's :inventory is account, current (the current realm's) or an inventory's id; account and current make the inventory if the player has none yet. A body that puts something somewhere takes inventoryId (one of the player's) or realmId (a realm's id, or null for the account); with neither, the definition decides: the account for what is held on the account, the current realm for what is held per realm or has no place of its own (cards).

Shapes

interface Realm {
  id: string
  number: number // unique here; 0 is the permanent realm
  key: string
  name: string
  enabled: boolean
  visible: boolean
  startAt: string
  endAt: string | null
}

interface Inventory {
  id: string
  realmId: string | null // null for the account inventory
}

interface Movement {
  transactionId: string
  inventoryId: string
  currencyKey: string
  amount: number // the signed change to the stored figure
  balanceAfter: number // for a consumed currency, what has been spent
  replayed: boolean // the Idempotency-Key named a movement already made
}

interface LedgerEntry {
  id: string
  inventoryId: string
  currencyKey: string
  amount: number
  balanceAfter: number
  reason: string
  reference: string | null
  createdAt: string
}

interface Item {
  id: string
  inventoryId: string
  itemTypeKey: string
  grantKey: string | null
  consumedAt: string | null
  data: object // your own fields
}

interface Card {
  id: string
  inventoryId: string
  cardTypeKey: string
  cardTemplateKey: string | null
  grantKey: string | null
  consumedAt: string | null
  data: object
}

interface Deck {
  id: string
  inventoryId: string
  name: string
  entries: { id: string; cardId: string | null; cardTypeKey: string | null; count: number }[]
}

interface Purchase<T> {
  replayed: boolean // true when the Idempotency-Key named a purchase already made
  charges: Movement[]
  granted: T | null // null when replayed
}

interface SkillTree {
  key: string
  name: string
  description: string
  hidden: boolean
  nodes: {
    key: string
    treeKey: string
    name: string
    description: string
    icon: string | null
    priceRule: 'all' | 'any'
    parents: string[] // nodes that must all be unlocked first
    prices: { currencyKey: string; amount: number }[]
    unlocked: boolean
    unlockable: boolean // not unlocked, and every parent is
  }[]
}

interface Stat {
  key: string
  value: string // a 64-bit counter, as a decimal string
}

Realms and inventories

  • GET /realms answers a list of every open Realm, newest first; GET /realms/current the current one, or not-found while none is open.
  • GET /players/:playerId/inventories answers a list of every Inventory the player has. GET /players/:playerId/inventories/:inventory answers one.
  • GET /players/:playerId/inventories/:inventory/balances answers a list of { currencyKey, amount }, with inventory beside it.
  • GET /players/:playerId/inventories/:inventory/items answers a list of the Items held one by one and not yet used, and .../item-stacks a list of the counted ones, { itemTypeKey, quantity }; each with inventory beside it.

GET /players/:playerId/ledger

The player's currency movements, newest first, a page at a time: a list of LedgerEntry.

Query Rules
currencyKey Optional. Only this currency's
inventoryId Optional. Only this inventory's

POST /players/:playerId/currencies/:currencyKey/credit, /debit, /refund, /consume

Server key, with an Idempotency-Key (required). Moves one currency: a retry answers the first receipt with replayed: true.

Field Type Rules
amount integer Required. How much, always positive: the route is the direction
allowance integer consume only, and required there: the most the player may have spent in all, after it
reason string Required. A key naming the flow, such as match.settlement
reference string Optional, 1 to 200 characters. What it was about: a match, an order
inventoryId string Optional. See Choosing an inventory
realmId string Optional, or null for the account

credit and debit are for balance currencies, consume for consumed ones; refund lowers what a consumed currency has spent, or credits a balance. Answers 200 with Movement. Refusals: insufficient-balance, allowance-exceeded, balance-cap, idempotency-conflict, invalid-request for the wrong kind of currency, not-found for no such currency.

Items

Granting and taking away items, counted cards and XP needs an Idempotency-Key, the same on every retry of that one request: a retry answers the first answer again and gives or takes nothing more.

POST /players/:playerId/items/grant, server key, with an Idempotency-Key.

Field Type Rules
itemTypeKey string Required
quantity integer Optional, 1 to 1,000; 1 when absent
grantKey string Optional, one-by-one types only, with a quantity of 1: granting again under it answers the first
data object Optional, one-by-one types only, up to 1 KB written compactly
inventoryId string Optional
realmId string Optional, or null

Answers { "inventoryId", "itemTypeKey", "stack": { "itemTypeKey", "quantity" } | null, "items": Item[], "alreadyGranted": boolean }. Refusals: disabled, owned-limit, invalid-request (a grant key or data on a counted type, or data over 1 KB).

POST /players/:playerId/items/:itemId/consume, server key, with an Idempotency-Key: takes one item away. Answers { "item": Item }. POST /players/:playerId/item-stacks/consume takes some of a counted type away, { "itemTypeKey", "quantity"?, "inventoryId"?, "realmId"? }, and answers { "stack": { "itemTypeKey", "quantity" } }. Refusals: already-consumed, insufficient-balance.

POST /players/:playerId/items/:itemId/use, either: uses, and so consumes, one item. POST /players/:playerId/item-stacks/use, either, with { "itemTypeKey", "inventoryId"?, "realmId"? }: uses one of a counted type. Each answers { "itemTypeKey", "item": Item | null }. Refusals: not-usable, locked (with details.missing), disabled, already-consumed.

POST /players/:playerId/items/:itemId/open, either. Opens a container (an item whose type's category is container), once. Answers as use. Refusals: not-usable for anything else, already-consumed.

Buying

POST /players/:playerId/purchases/items, either. An optional Idempotency-Key makes a retry answer the first purchase.

Field Type Rules
itemTypeKey string Required
quantity integer Optional, 1 to 100: every price is multiplied by it
inventoryId string Optional. The inventory it goes to; its realm pays what is held per realm
realmId string Optional. The realm that pays what is held per realm
payWith string Optional. For a price list paid with any one price: the currency to pay in
allowances object Server key only: what the game allows of each consumed currency, by its key

Answers 200 with Purchase of the item grant. Refusals: not-purchasable, disabled, insufficient-balance, owned-limit, invalid-request for a consumed currency without its allowance, forbidden for allowances from a player's token.

POST /players/:playerId/purchases/cards, either. cardTypeKey (required), as (instance, the default, for a card of its own, or stack for one more of a counted type), inventoryId, realmId, payWith; with a server key also cardTemplateKey, data (up to 1 KB) and allowances. Answers Purchase of { "card": Card, "alreadyGranted" } or of a card stack { "inventoryId", "cardTypeKey", "quantity" }.

Cards and decks

GET /players/:playerId/inventories/:inventory/cards answers a list of the Cards held one by one, and .../card-stacks a list of the counted ones, { "inventoryId", "cardTypeKey", "quantity" }; each with inventory beside it.

POST /players/:playerId/cards/grant, server key. cardTypeKey (required), cardTemplateKey, grantKey, data (up to 1 KB), inventoryId, realmId. Answers { "card": Card, "alreadyGranted": boolean }.

POST /players/:playerId/cards/:cardId/consume, server key. Takes the card away, and out of every deck. Answers Card.

POST /players/:playerId/card-stacks/grant and /card-stacks/consume, server key, with an Idempotency-Key. { "cardTypeKey", "quantity", "inventoryId"?, "realmId"? }, quantity 1 to 1,000. Answers the stack.

Decks, either credential, a player's token for its own:

  • GET /players/:playerId/decks[?inventoryId=] answers a list of Deck.
  • POST /players/:playerId/decks with { "inventoryId", "name" } (name 1 to 60 characters after trimming) answers 201 with Deck; owned-limit past 50 decks.
  • GET and PATCH ({ "name" }) on /players/:playerId/decks/:deckId answer Deck; DELETE answers 204.
  • PUT /players/:playerId/decks/:deckId/cards/:cardId puts an owned card in the deck, and DELETE takes it out; both are edits of the deck, and answer it.
  • PUT /players/:playerId/decks/:deckId/types/:cardTypeKey with { "count" } (0 to 1,000; 0 takes the line out) sets how many of a type, and answers the deck.
  • A deck holds up to 200 lines (owned-limit). GET /players/:playerId/decks/:deckId/validation[?maxSize=] answers { "valid", "size", "problems": { "code", "message", "cardTypeKey"?, "cardId"? }[] } with code one of size, per-type-limit, not-owned, unknown-card-type, disabled-card-type.

Progression

  • GET /players/:playerId/xp answers a list of { "track", "xp" }. POST /players/:playerId/xp, server key, with an Idempotency-Key and { "amount", "track"? }, answers { "track", "xp" }, the new total (a retry answers the first total).
  • GET /players/:playerId/skill-trees answers a list of SkillTree, leaving hidden trees out for a player's token; GET /players/:playerId/skill-trees/:treeKey answers one SkillTree.
  • POST /players/:playerId/skill-nodes/:nodeKey/unlock, either, with { "realmId"?, "payWith"?, "allowances"? } (allowances from a server key only) answers { "nodeKey", "alreadyUnlocked", "charges": Movement[] }. Refusals: locked (with details.missing), insufficient-balance, allowance-exceeded, invalid-request for a consumed currency without its allowance, forbidden in a GreenMind game whose skill trees are unlocked by the game itself.
  • GET /players/:playerId/unlocks[?prefix=] answers a list of { "key", "source", "unlockedAt" }. PUT /players/:playerId/unlocks/:key, server key, with { "source"? } answers the unlock: 201 when this recorded it, 200 when it was recorded already, the first record standing. DELETE answers 204, whether or not the player held it.

Stats

  • GET /players/:playerId/stats[?realmId=] and GET /stats[?realmId=] answer a list of Stat, across every realm when no realm is named.
  • POST /players/:playerId/stats/:key/increment and POST /stats/:key/increment, server key, with { "by"?, "realmId"? } (by a whole number other than 0, 1 when absent, either sign; realmId null or absent for across every realm) answer Stat, the new value.

Definitions

Server key. Definitions are edited in the console; these read them, each a page at a time. Switched-off definitions are listed with enabled: false; deleted ones are not listed.

Route A list of
GET /definitions/realms Realm, open or not
GET /definitions/currencies { key, name, description, icon, scope, kind, max }
GET /definitions/item-types Item types, each with category, ownership, scope, switches, maxOwned, priceRule, prices and data
GET /definitions/card-types Card types, each with slug, perDeckLimit, starter, purchasable, priceRule, prices and data
GET /definitions/card-templates { key, name, description, enabled, data }
GET /definitions/skill-trees Skill trees, each node with its parents and prices

When an environment is full. Once an environment holds as many players as your plan allows (1,000 on the Free plan), signing in a player it has never seen is refused with 409 and conflict, and message says so. Players it already has keep signing in, and nothing is deleted. The console's Usage page marks the environment as full. To raise the cap, an admin of the org asks GreenMind for a higher plan with Request a higher plan on that page; deleting players you no longer need frees room in the meantime. See Getting started for how plans are asked for.

Actions

POST /actions/:action

Either credential, with an Idempotency-Key and { "input": ... }. Runs the flow your environment's action of this name triggers, inside the call, and answers once the flow has committed its writes or refused: { "outcome": "done", "runId", "answer" }, or { "outcome": "refused", "runId", "refusal": { "code", "params"? } }, which your game words from refusal.code. Sending the same key again answers what the first call did. A flow that cannot finish in time answers as its onTimeout says and finishes afterwards. Refusals: not-found (no such action, or the environment runs none), conflict (the first call with this key is still running; send it again), unavailable (try again after Retry-After).

A flow's refusal is the flow's answer, not an error of the call, so it comes back as 200 with outcome: "refused".

Events

POST /events/:event

Either credential, with an Idempotency-Key and { "payload": ... }, up to 64 KB. Sends one of your environment's own events to the flows that start on it, and answers { "eventId", "outcome" }: accepted when a live flow starts on the event, dropped when none does. The event must be declared and live in the environment (defineEvent), and the payload must fit its declared payload. A server key sends an event whose declaration lets servers send it, which is the default; a player's token sends only one whose sentBy lists player, and a flow it starts is untrusted. A player sends an event ordered by player only about themselves. Names in the platform's own namespaces (player., purchase., currency. and the others in the events reference) are never sent this way. Sending the same key again is the same event, and no flow runs twice for it; the key is yours alone, so another server key or player using it sends an event of its own. Refusals: not-found (no such event declared, or the environment runs no flows), forbidden (the credential may not send this event, or the name is the platform's), invalid-request (a payload that does not fit, named in details.field), unavailable (try again after Retry-After).

Collections

Your environment's own data, in the collections you define: rows checked against each collection's fields, a few fields indexed so a query on them is fast. One pair of calls reaches every collection, so adding one needs nothing new in your game. Only an environment on flows has collections; elsewhere both calls answer not-found.

POST /collections/:collection/query

Either credential. { "owner", "key" } reads one row; { "query", "where": { field: value }, "owner"?, "limit"?, "after"? } runs one of the collection's declared queries, with a value for each field it filters on, and answers a page: { "rows": [{ owner, key, data, version, updatedAt }], "next"? }. Pass next as after for the following page. Only declared queries run, and only on their indexed fields: a field whose index is still being built answers unavailable with Retry-After, never a slow scan. A player reads their own rows of a collection read by its owner, and every row of one open to all players; the rest is forbidden. A data older than the collection's current shape is upgraded on the way out. Refusals: not-found (no such collection or query), forbidden, invalid-request (a value that does not fit its field, named in details.field), unavailable.

POST /collections/:collection/write

Either credential, with an Idempotency-Key and { "writes": [{ "op": "put", owner, key, data, expectVersion? } | { "op": "delete", owner, key, expectVersion? }] }, up to 100, applied together or not at all. Answers { "outcome": "done", "versions" }, { "outcome": "conflict", "index", "version" } when write index named a version the row no longer has ("0" expects no row), or { "outcome": "refused", "index", "refusal": { "code", "params" } } for a row that does not fit the collection (params.path names the field), one the caller may not write, or one past the environment's row or storage limits. A player writes only their own rows, and only the fields the collection lets players write. Sending the same key again answers what the first call did.

Reads

POST /reads

Either credential. { "reads": { "<name>": { "op", "args" } } }, 1 to 32 of the engine's reads (currencies.balances, cards.list, items.list, unlocks.list, decks.list, stats.player, config.value ...), answered together as { "data": { "<name>": ... } }. A player reads only their own rows (a read naming another player, or another player's inventory or deck, is forbidden) and never config; a server key reads every row of its environment. Only an environment on flows has reads; elsewhere it answers not-found. Refusals: not-found, forbidden, invalid-request (a read that is not one), unavailable.

Extension definitions

What the extension tool (gm pub check, gm pub push, gm pub upload, gm pub deploy) calls, with an environment's publish key (gmext_...), which names the environment, or as a person signed in to the gm command, who names it as ?appKey=. No call takes the environment from its body. A person needs view_config there to check and edit_config to change anything, held to the level they gave the command; a protected environment is refused a change whoever asks, and each change a person makes is in the environment's audit log. Check and push take { "definitions": [...] }, each { kind, key, body, contentHash, declaredOperations? } as gm pub compile writes it.

POST /ext/definitions/check

Answers { "environment": { "appKey", "protected" }, "issues": [{ kind, key, step?, code, message }] } and changes nothing. An empty issues means a push would be taken. A flow in an environment placed on a game database is also checked by the engine: its graph, expressions and limits. A definition is refused when its body is not its kind's stored form, its key or contentHash is not its body's, it is sent twice, or it declares an operation the platform does not have.

POST /ext/definitions/push

Saves each definition as a new version in the environment, unless its latest version already has the same content, and answers { "environment", "results": [{ kind, key, versionId, contentHash, created }] }. Every definition is checked before any is saved, and they are saved together or not at all: a push with an issue is refused with invalid-request and the issues in details.issues. source ({ repository?, commit?, branch? }) is kept with each version. A protected environment (production) is refused, with forbidden for a publish key and protected-environment for a person: its definitions change by a release. A push saves versions; making one live is done in the console or by a release, unless the push sets "live": true, which also makes each pushed version live and answers "live": true. Where the environment is placed on a game database, each flow is also asked of the engine, and a refusal names the step it is about (step).

POST /ext/definitions/flows/switch

Switches flows of the key's environment on or off: { "flows": [{ key, enabled }] }, at most 200, each a flow the environment has (not-found, with the ones it has not in details.flows, and nothing switched). A flow switched on starts taking its triggers; one switched off stops. Answers { "flows": [...] } as they now stand. A person signed in to the gm command may call it too, with edit_config in the environment, naming it as ?appKey=. A protected environment (production) is refused with protected-environment, whoever asks: its flows change by a release. Each flow switched is in the environment's audit log.

POST /ext/definitions/config-defaults

Gives the key's environment the config values it lacks, for a build whose functions refuse to run without their balancing values: { "values": [{ name, type, value }] }, at most 200, type one of int, float, bool and object. A value the environment holds is left exactly as it is, so a designer's retune survives every build; one it lacks, or that was deleted, is written as given. Answers { "seeded": [name] }, the names this call wrote. A person signed in to the gm command may call it too, as above. A protected environment (production) is refused with protected-environment: its config changes by a release. What a call wrote is in the environment's audit log.

POST /ext/functions/upload

What gm pub upload sends: one built bundle of hosted functions, { "bundle": "<index.mjs as base64>", "contentHash": "<SHA-256 of its bytes>", "runtime": "nodejs24.x", "definitions": [...], "source"? }, where definitions are the functions the bundle holds, compiled as gm pub compile writes them. The bundle is kept by its hash, at most 10 MB, and each function is saved as a version that runs it; the same body over a new bundle is a new version. Answers { "environment", "artifact": { contentHash, sizeBytes, created }, "results": [{ kind, key, versionId, contentHash, created }], "deployment": { target, functionName? } }. A bundle whose bytes are not its contentHash, or anything but functions in definitions, is invalid-request. A protected environment (production) is refused, with forbidden for a publish key and protected-environment for a person: a release moves the bundle tested in a test environment there, by its hash. unavailable means the bundle could not be kept or its function not yet updated; send it again.

Extension environments

What the gm command calls for a person signed in to it (gm login): a GreenMind sign-in for the command, naming no environment. Every call is checked against what the person may do in the environment it names, as in the console, and held to the level they gave the command for it at consent. None of them changes a protected environment: that is done in the console, or in a release. An environment the person may not see is unknown-environment, as one that does not exist is.

GET /ext/environments

The environments the person may read and gave the command, each { appKey, name, environment, protected, project, org, level }. Needs the ext:read scope.

GET /ext/environments/:appKey/status

Everything gm pub env status prints: the game database it is on and who writes its game data, where its functions run, its definitions by kind with each one's live version, flows on of total, the newest landing and how many server and publish keys it has. A person with view_config there, or the environment's own publish key.

GET /ext/environments/:appKey/server-keys

Its server keys, by name and prefix, never a key. POST with { "name" } makes one and answers { key, secret }, the key in that answer and nowhere else; DELETE /ext/environments/:appKey/server-keys/:keyId revokes one. A person with manage_server_keys there and the ext:manage scope. A protected environment gets new keys only in the console (protected-environment); a key can be revoked anywhere.

GET /ext/environments/:appKey/publish-keys

The same for publish keys, by label: POST with { "label" }, and DELETE /ext/environments/:appKey/publish-keys/:keyId.

GET /ext/environments/:appKey/function-runtime

Where its functions are to run, the runtimes its organisation may use and where they run now. PUT with { "runtime": "lambda" | "host" | null } chooses, or follows the stage default with null, and asks for the move at once: a person with edit_config there and the ext:manage scope, in a test environment. A runtime the organisation may not use is runtime-not-allowed, with those it may in details.allowed.

GET /ext/environments/:appKey/collection-storage

Where its collections may keep their rows: every storage mode (collection, dedicated, self-hosted) with whether it may be used now and, where not, why (not-granted, not-placed, shared-database, not-served, needs-connection); its own default for new collections, its organisation's and the one in force; and each collection's mode as the engine holds it, or collections: null where the engine could not be asked. A person with view_config there and the ext:read scope. PUT with { "default": "collection" | "dedicated" | null } sets the default for collections whose definitions name no mode, or follows the organisation's with null: a person with edit_config there and the ext:manage scope, in a test environment. A mode the organisation may not use, and self-hosted, which needs a connection named in a definition, are storage-not-allowed, with those it may choose in details.allowed.

POST /ext/environments/:appKey/connections/:connection/check

Checks a data connection's connector for self-hosted collections: the connector check for protocol 2, run through the engine and the server socket against the environment's connected server that answers the connection. It writes only rows of the check's own collection and erases them, and keeps the result on the connection. Answers each rule and whether it passed, the slowest call, and until when a pass is fresh: a collection may name the connection as its self-hosted storage while its last check passed and is under 30 days old. A person with edit_config there and the ext:manage scope. Refusals: not-found (no such connection), invalid-request (not a data connection).

A call that changes something is checked with GreenMind as well as by the sign-in's own signature, so a sign-in revoked is refused at once rather than when its token ends. unavailable means GreenMind could not be asked just then: nothing was changed, and the same call may be sent again.

GET /ext/tool

No credential: where the gm command signs in on this platform, before anybody has. Answers { issuer, clientId, scopes }: the GreenMind accounts server to sign in with, the command's client, and the scopes a sign-in asks for. gm login reads it, and a flag overrides each.

Connections

How your environment's flows are reached from outside, and how your own backend knows a request came from them.

POST /ext/webhooks/:appKey/:connection

No credential: give this address to a service as its webhook URL, for an incoming webhook connection made on the environment's Connections page. The body is taken exactly as sent (at most 256 KB) and checked against the connection's signing secret by that service's own rule: Linear's Linear-Signature, GitHub's X-Hub-Signature-256, or Standard Webhooks' webhook-id, webhook-timestamp and webhook-signature. It then starts each flow whose trigger is this connection, once per delivery: a delivery sent again starts nothing more. Answers 204. Refusals: unauthorized (the signature does not match, or the delivery is too old), not-found (no such connection, or the environment is not on flows), payload-too-large, unavailable (send it again).

POST /ext/webhooks/:appKey/:connection/:token

For a service that cannot sign what it sends: the address is the secret, its last part a token shown once when the connection is made, and a flow such a delivery starts is treated as untrusted, as a player's own event is. Otherwise as above.

GET /.well-known/ext-endpoint-jwks.json

No credential. The public keys the engine signs its requests to your own endpoint, event sink and data connector with. Check every request's bearer token against these, as the serving kit does: issuer gm-platform, audience your endpoint's own address exactly as the connection names it, type ext-endpoint or ext-sink, bh the base64url SHA-256 of the body, a lifetime of sixty seconds, and each jti taken once.

Errors

Every code a program may meet, and its status. The same list is in the OpenAPI document, as the Error schema's error.

error Status Meaning
invalid-request 400 The body is not JSON, or a field, query parameter, path parameter or header is missing, malformed, past a limit, or one the route does not take; details.field names it
invalid-ticket 400 The store refused the proof of identity a client sent
unauthorized 401 No credential, or one that is malformed, unknown, revoked or expired; a refresh token sent as an access token; a player signed out everywhere; a failed sign-in
forbidden 403 The credential is the wrong kind for the route, or a player's token sent what only a server may
service-disabled 403 The project has not switched on the service the route belongs to
project-not-approved 403 The project is waiting for GreenMind's review, was not approved, or was suspended: no credential of it is let in and no sign-in to it succeeds until GreenMind approves it
provider-disabled 403 The environment does not accept that way of signing in
quota-exceeded 403 A limit on how many of something there may be: players or saved bytes in an environment, a player's saves, a licence's seats. details.quota and details.limit say which
purchase-not-allowed 403 The store will not let this player buy
not-found 404 No such thing in this environment, or no such route. A thing of another environment is not-found too
conflict 409 The request clashes with the current state: a full lobby, a seat already taken, a status move that is not allowed, a save written by somebody else since
idempotency-conflict 409 The Idempotency-Key already names a different request
insufficient-balance 409 Not enough of a currency or a counted thing; details has what is held and what was asked
allowance-exceeded 409 A consumed currency would pass the allowance the game sent
balance-cap 409 A credit would take a balance past its currency's most
disabled 409 The definition it needs is switched off
not-purchasable 409 That is not for sale
owned-limit 409 The player already holds as many as the definition, or a deck, allows
locked 409 It needs unlocks or skill nodes the player does not have; details.missing lists them
not-usable 409 That item cannot be used or opened
already-consumed 409 Already used, opened or spent
no-current-realm 409 No realm is open now
no-steam-account 409 The player has proved no Steam account
already-active 409 The player already holds that product, and it cannot be held twice
order-in-progress 409 An order for that product is already waiting for the player
payload-too-large 413 The body is bigger than its route takes; details.limit is the most, in bytes
rate-limited 429 Too many requests: see Rate limits. Always with Retry-After
provider-refused 502 The store answered with an error of its own
unavailable 503 Something the route needs cannot be reached, or is not set up here. Retry later

The console answers three codes of its own, which the API never does: agreements-required, key-taken and invite-invalid.