Platform API reference
The NEO Platform's HTTP API: protocol, authentication, errors, and every service generated from the API's contract.
The NEO Platform API is what the web app, the Studio and the desktop client use: accounts, games, sessions, the Marketplace, the wallet and the Creator Hub. These pages are generated from the API's contract (its .proto files) and its routes, so every method and field listed here is real.
Protocol#
The API speaks the Connect protocol's unary JSON form. Every method is an HTTP POST to /neo.platform.v1.<Service>/<Method> on your platform's API URL, with a JSON body (Content-Type: application/json). An empty body is the same as {}.
curl -X POST "$NEO_API/neo.platform.v1.CatalogService/ListExperiences" \
-H 'Content-Type: application/json' \
-d '{"sort": "popular"}'JSON follows the proto3 JSON mapping:
- Field names are camelCase (
displayName); the snake_case names (display_name) are accepted too. - 64-bit integers (
int64) are JSON strings ("1250"), so they stay exact in JavaScript. Ids are strings. - Fields at their default value (
0,"",false, empty lists) may be left out of responses: read a missing field as its default. - Unknown fields in a request are ignored, so newer clients can talk to older servers.
Authentication#
Methods that need a caller take a bearer token: Authorization: Bearer <access token>. SignIn and SignUp return an access token and a refresh token; Refresh exchanges the refresh token for new ones. Each method's Auth line says what it needs:
| Auth | Who can call |
|---|---|
| Account | A signed-in account. Guests get permission_denied. |
| Account or guest | A signed-in account or a guest (see StartGuest). |
| Optional | Anyone. A signed-in caller gets personalised fields, such as whether they favorited a game. |
| None | Anyone. |
A token stops working as soon as its device is signed out, the password changes or the account is deleted, not only when it expires.
Scoped tokens. Pages that embed the Studio or the avatar editor get a short-lived scoped token from IssueScopedToken. A scoped token can call only its scope's methods (the studio scope: publishing games; the avatar scope: the AvatarService), each listed on its method below.
The optional x-neo-client header names the client in the account's list of signed-in devices (for example Web · Chrome).
Errors#
A failed call answers with an HTTP error status and a JSON body {"code": "...", "message": "..."}. The message is readable text you can show.
| Code | HTTP status | Meaning |
|---|---|---|
invalid_argument | 400 | A field is missing or invalid. |
failed_precondition | 400 | The request is valid but the state doesn't allow it (for example, not enough Credits). |
unauthenticated | 401 | No token, or the token is invalid or expired. |
permission_denied | 403 | The caller may not do this (a guest, someone else's game, a scoped token outside its scope). |
not_found | 404 | The record doesn't exist or isn't visible to the caller. |
already_exists | 409 | A unique value is taken (a username, for example). |
resource_exhausted | 429 | Too many requests: slow down and retry. |
internal | 500 | Something failed on the server. |
Services#
| Service | What it covers |
|---|---|
| IdentityService | Accounts, sign-in, guests, devices and account settings. |
| SocialService | Profiles, friends, follows, communities (groups) and blocking. |
| CatalogService | Games: creating, publishing versions, discovery, ratings, content uploads and testers. |
| SessionService | Joining games: sessions, heartbeats, presence in a session and invites. |
| EconomyService | The wallet, NEO Credits packs, the Marketplace's items, buying and inventory. |
| AvatarService | Reading and saving the player's avatar. |
| ChatService | Conversations and read state. |
| CreatorService | The Creator Hub: overview, analytics, sales, uploads and payouts. |
| SafetyService | Reporting players and experiences to moderation. |
| DatastoreService | Game save data: a running game's per-player and shared data, leaderboards, and the player's data export. |
Common types#
Types several services use.
Item#
| Field | Type | Description |
|---|---|---|
id | string | |
kind | string | avatar_hat, avatar_shirt, avatar_emote, game_pass, developer_product |
name | string | |
description | string | |
price | string (int64) | |
creatorId | string | |
creatorName | string | |
experienceId | string | |
thumbnailUrl | string | |
owned | boolean | |
sales | string (int64) |
PageRequest#
| Field | Type | Description |
|---|---|---|
pageSize | number | |
pageToken | string |
UserSummary#
A user as other people see them.
| Field | Type | Description |
|---|---|---|
id | string | |
username | string | |
displayName | string | |
headshotUrl | string | URL of the avatar headshot (rendered by the platform). |