Defines stat configurations, records player stat items, and exposes ranked leaderboards (all-time, weekly, monthly) built on top of tracked statistics.
openapi: 3.0.3
info:
title: AccelByte Gaming Services (AGS) API
description: >-
Representative OpenAPI description of the core AccelByte Gaming Services
(AGS) REST surface. AGS is delivered as a set of independent microservices
(IAM, Basic, Cloud Save, Statistics/Leaderboard, Matchmaking, Session,
Platform/Commerce, Season Pass, Achievement, DSMC/Armada, Game Telemetry,
and UGC), each mounted under its own path prefix on the environment base
URL (for example https://demo.accelbyte.io). Almost every operation is
scoped to a `namespace` path parameter and secured with an OAuth2
Bearer access token issued by IAM. This document models a representative
slice of each service rather than the exhaustive per-service specs, which
AccelByte publishes individually.
termsOfService: https://accelbyte.io/terms-of-service
contact:
name: AccelByte
url: https://accelbyte.io/contact-us
version: '1.0'
servers:
- url: https://demo.accelbyte.io
description: Shared AccelByte demo environment
- url: https://{namespace}.accelbyte.io
description: Customer environment base URL
variables:
namespace:
default: demo
description: Customer environment host prefix
security:
- bearerAuth: []
tags:
- name: IAM
description: Identity and Access Management - OAuth2 tokens, users, roles.
- name: Basic
description: Player profiles and basic user data.
- name: Cloud Save
description: Player and game record storage.
- name: Statistics
description: Player statistics and configurations.
- name: Leaderboard
description: Ranked leaderboards derived from statistics.
- name: Matchmaking
description: Matchmaking V2 pools and tickets.
- name: Session
description: Game sessions and parties (Session V2).
- name: Platform
description: Commerce - stores, items, entitlements, wallets, orders.
- name: Season Pass
description: Seasons, passes, tiers, and rewards.
- name: Achievement
description: Achievement definitions and player unlocks.
- name: DSMC
description: Dedicated Server Manager (Armada) fleets and sessions.
- name: Game Telemetry
description: Gameplay and client telemetry ingestion.
- name: UGC
description: User-generated content channels and contents.
paths:
/iam/v3/oauth/token:
post:
operationId: iamGetToken
tags:
- IAM
summary: Issue an OAuth2 access token.
description: >-
OAuth2 token endpoint. Supports `client_credentials` for server-to-server
access, `authorization_code` for player login flows, and
`urn:ietf:params:oauth:grant-type:token-exchange` / platform token
exchange for linking third-party platform accounts. Clients authenticate
with HTTP Basic (client id / client secret).
security:
- basicAuth: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- grant_type
properties:
grant_type:
type: string
enum:
- client_credentials
- authorization_code
- refresh_token
- urn:ietf:params:oauth:grant-type:token-exchange
example: client_credentials
code:
type: string
description: Authorization code (authorization_code grant).
redirect_uri:
type: string
refresh_token:
type: string
code_verifier:
type: string
description: PKCE code verifier.
responses:
'200':
description: Token issued.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/iam/v3/public/namespaces/{namespace}/users:
post:
operationId: iamCreateUser
tags:
- IAM
summary: Register a new user account.
parameters:
- $ref: '#/components/parameters/Namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
responses:
'201':
description: User created.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
/iam/v3/public/namespaces/{namespace}/users/me:
get:
operationId: iamGetMyUser
tags:
- IAM
summary: Get the current authenticated user.
parameters:
- $ref: '#/components/parameters/Namespace'
responses:
'200':
description: The current user.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/Unauthorized'
/basic/v1/public/namespaces/{namespace}/users/{userId}/profiles:
get:
operationId: basicGetUserProfile
tags:
- Basic
summary: Get a player's profile.
parameters:
- $ref: '#/components/parameters/Namespace'
- $ref: '#/components/parameters/UserId'
responses:
'200':
description: Player profile.
content:
application/json:
schema:
$ref: '#/components/schemas/UserProfile'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: basicUpdateUserProfile
tags:
- Basic
summary: Update a player's profile.
parameters:
- $ref: '#/components/parameters/Namespace'
- $ref: '#/components/parameters/UserId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserProfile'
responses:
'200':
description: Updated profile.
content:
application/json:
schema:
$ref: '#/components/schemas/UserProfile'
/cloudsave/v1/namespaces/{namespace}/users/{userId}/records/{key}:
get:
operationId: cloudSaveGetPlayerRecord
tags:
- Cloud Save
summary: Get a player record by key.
parameters:
- $ref: '#/components/parameters/Namespace'
- $ref: '#/components/parameters/UserId'
- $ref: '#/components/parameters/RecordKey'
responses:
'200':
description: The player record.
content:
application/json:
schema:
$ref: '#/components/schemas/PlayerRecord'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: cloudSaveCreatePlayerRecord
tags:
- Cloud Save
summary: Create or replace a player record.
parameters:
- $ref: '#/components/parameters/Namespace'
- $ref: '#/components/parameters/UserId'
- $ref: '#/components/parameters/RecordKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: Record saved.
content:
application/json:
schema:
$ref: '#/components/schemas/PlayerRecord'
/social/v1/namespaces/{namespace}/users/{userId}/statitems:
get:
operationId: statisticsGetUserStatItems
tags:
- Statistics
summary: List a player's stat items.
parameters:
- $ref: '#/components/parameters/Namespace'
- $ref: '#/components/parameters/UserId'
responses:
'200':
description: A page of stat items.
content:
application/json:
schema:
$ref: '#/components/schemas/StatItemPagedResponse'
/social/v1/namespaces/{namespace}/users/{userId}/statitems/value/bulk:
put:
operationId: statisticsBulkUpdateStatItems
tags:
- Statistics
summary: Bulk update a player's stat item values.
parameters:
- $ref: '#/components/parameters/Namespace'
- $ref: '#/components/parameters/UserId'
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/StatItemUpdate'
responses:
'200':
description: Updated stat items.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/StatItem'
/leaderboard/v1/public/namespaces/{namespace}/leaderboards/{leaderboardCode}/all:
get:
operationId: leaderboardGetAllTimeRanking
tags:
- Leaderboard
summary: Get all-time leaderboard rankings.
parameters:
- $ref: '#/components/parameters/Namespace'
- name: leaderboardCode
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: Ranked entries.
content:
application/json:
schema:
$ref: '#/components/schemas/LeaderboardRankingResult'
/match2/v1/namespaces/{namespace}/match-tickets:
post:
operationId: matchmakingCreateTicket
tags:
- Matchmaking
summary: Submit a match ticket.
parameters:
- $ref: '#/components/parameters/Namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MatchTicketRequest'
responses:
'201':
description: Ticket created.
content:
application/json:
schema:
$ref: '#/components/schemas/MatchTicket'
/match2/v1/namespaces/{namespace}/match-tickets/{ticketId}:
delete:
operationId: matchmakingDeleteTicket
tags:
- Matchmaking
summary: Cancel a match ticket.
parameters:
- $ref: '#/components/parameters/Namespace'
- name: ticketId
in: path
required: true
schema:
type: string
responses:
'204':
description: Ticket cancelled.
/session/v1/public/namespaces/{namespace}/gamesession:
post:
operationId: sessionCreateGameSession
tags:
- Session
summary: Create a game session.
parameters:
- $ref: '#/components/parameters/Namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GameSessionRequest'
responses:
'201':
description: Game session created.
content:
application/json:
schema:
$ref: '#/components/schemas/GameSession'
/session/v1/public/namespaces/{namespace}/party:
post:
operationId: sessionCreateParty
tags:
- Session
summary: Create a party session.
parameters:
- $ref: '#/components/parameters/Namespace'
responses:
'201':
description: Party created.
content:
application/json:
schema:
$ref: '#/components/schemas/PartySession'
/platform/public/namespaces/{namespace}/items/byCriteria:
get:
operationId: platformQueryItems
tags:
- Platform
summary: Query catalog items by criteria.
parameters:
- $ref: '#/components/parameters/Namespace'
- name: storeId
in: query
schema:
type: string
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: A page of catalog items.
content:
application/json:
schema:
$ref: '#/components/schemas/ItemPagedResponse'
/platform/public/namespaces/{namespace}/users/{userId}/entitlements:
get:
operationId: platformGetUserEntitlements
tags:
- Platform
summary: List a user's entitlements.
parameters:
- $ref: '#/components/parameters/Namespace'
- $ref: '#/components/parameters/UserId'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: A page of entitlements.
content:
application/json:
schema:
$ref: '#/components/schemas/EntitlementPagedResponse'
/platform/public/namespaces/{namespace}/users/{userId}/orders:
post:
operationId: platformCreateOrder
tags:
- Platform
summary: Create an order (checkout).
parameters:
- $ref: '#/components/parameters/Namespace'
- $ref: '#/components/parameters/UserId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRequest'
responses:
'201':
description: Order created.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
/platform/public/namespaces/{namespace}/users/{userId}/wallets/{currencyCode}:
get:
operationId: platformGetUserWallet
tags:
- Platform
summary: Get a user's wallet for a currency.
parameters:
- $ref: '#/components/parameters/Namespace'
- $ref: '#/components/parameters/UserId'
- name: currencyCode
in: path
required: true
schema:
type: string
responses:
'200':
description: The wallet.
content:
application/json:
schema:
$ref: '#/components/schemas/Wallet'
/seasonpass/v1/public/namespaces/{namespace}/seasons/current/progression:
get:
operationId: seasonPassGetCurrentProgression
tags:
- Season Pass
summary: Get the player's progression in the current season.
parameters:
- $ref: '#/components/parameters/Namespace'
responses:
'200':
description: Current season progression.
content:
application/json:
schema:
$ref: '#/components/schemas/UserSeasonProgression'
/achievement/v1/public/namespaces/{namespace}/users/{userId}/achievements:
get:
operationId: achievementListUserAchievements
tags:
- Achievement
summary: List a player's achievements.
parameters:
- $ref: '#/components/parameters/Namespace'
- $ref: '#/components/parameters/UserId'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: A page of user achievements.
content:
application/json:
schema:
$ref: '#/components/schemas/UserAchievementPagedResponse'
/dsmcontroller/namespaces/{namespace}/servers/claim:
post:
operationId: dsmcClaimServer
tags:
- DSMC
summary: Claim a ready dedicated server.
parameters:
- $ref: '#/components/parameters/Namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ClaimServerRequest'
responses:
'200':
description: Claimed server.
content:
application/json:
schema:
$ref: '#/components/schemas/DedicatedServer'
/game-telemetry/v1/protected/events:
post:
operationId: telemetrySaveEvents
tags:
- Game Telemetry
summary: Save a batch of telemetry events.
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TelemetryEvent'
responses:
'204':
description: Events accepted.
/ugc/v1/public/namespaces/{namespace}/channels/{channelId}/contents/s3:
post:
operationId: ugcCreateContent
tags:
- UGC
summary: Create UGC content in a channel.
parameters:
- $ref: '#/components/parameters/Namespace'
- name: channelId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateContentRequest'
responses:
'201':
description: Content created (with a presigned upload URL).
content:
application/json:
schema:
$ref: '#/components/schemas/Content'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: OAuth2 access token issued by the IAM token endpoint.
basicAuth:
type: http
scheme: basic
description: OAuth2 client id / client secret used at the token endpoint.
parameters:
Namespace:
name: namespace
in: path
required: true
description: The game namespace the request is scoped to.
schema:
type: string
example: demogame
UserId:
name: userId
in: path
required: true
schema:
type: string
RecordKey:
name: key
in: path
required: true
schema:
type: string
Limit:
name: limit
in: query
required: false
schema:
type: integer
default: 20
Offset:
name: offset
in: query
required: false
schema:
type: integer
default: 0
responses:
BadRequest:
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Missing or invalid access token.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
ErrorResponse:
type: object
properties:
errorCode:
type: integer
description: AccelByte numeric error code.
errorMessage:
type: string
required:
- errorCode
- errorMessage
Paging:
type: object
properties:
previous:
type: string
next:
type: string
TokenResponse:
type: object
properties:
access_token:
type: string
token_type:
type: string
example: Bearer
expires_in:
type: integer
refresh_token:
type: string
namespace:
type: string
scope:
type: string
required:
- access_token
- token_type
- expires_in
CreateUserRequest:
type: object
properties:
authType:
type: string
enum:
- EMAILPASSWD
default: EMAILPASSWD
emailAddress:
type: string
format: email
password:
type: string
displayName:
type: string
country:
type: string
description: ISO 3166-1 alpha-2 country code.
dateOfBirth:
type: string
format: date
required:
- authType
- emailAddress
- password
User:
type: object
properties:
userId:
type: string
namespace:
type: string
emailAddress:
type: string
displayName:
type: string
country:
type: string
emailVerified:
type: boolean
UserProfile:
type: object
properties:
userId:
type: string
namespace:
type: string
firstName:
type: string
lastName:
type: string
avatarUrl:
type: string
language:
type: string
timeZone:
type: string
customAttributes:
type: object
additionalProperties: true
PlayerRecord:
type: object
properties:
key:
type: string
namespace:
type: string
user_id:
type: string
value:
type: object
additionalProperties: true
is_public:
type: boolean
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
StatItem:
type: object
properties:
statCode:
type: string
userId:
type: string
value:
type: number
namespace:
type: string
StatItemUpdate:
type: object
properties:
statCode:
type: string
inc:
type: number
description: Increment applied to the current value.
required:
- statCode
- inc
StatItemPagedResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/StatItem'
paging:
$ref: '#/components/schemas/Paging'
LeaderboardRankingResult:
type: object
properties:
leaderboardCode:
type: string
data:
type: array
items:
$ref: '#/components/schemas/RankingEntry'
RankingEntry:
type: object
properties:
userId:
type: string
rank:
type: integer
point:
type: number
MatchTicketRequest:
type: object
properties:
matchPool:
type: string
sessionID:
type: string
attributes:
type: object
additionalProperties: true
latencies:
type: object
additionalProperties:
type: integer
required:
- matchPool
MatchTicket:
type: object
properties:
matchTicketID:
type: string
queueTime:
type: integer
matchPool:
type: string
GameSessionRequest:
type: object
properties:
configurationName:
type: string
matchPool:
type: string
joinability:
type: string
enum:
- OPEN
- CLOSED
- INVITE_ONLY
maxPlayers:
type: integer
required:
- configurationName
GameSession:
type: object
properties:
id:
type: string
namespace:
type: string
configurationName:
type: string
joinability:
type: string
members:
type: array
items:
$ref: '#/components/schemas/SessionMember'
dsInformation:
type: object
additionalProperties: true
PartySession:
type: object
properties:
id:
type: string
namespace:
type: string
leaderId:
type: string
members:
type: array
items:
$ref: '#/components/schemas/SessionMember'
SessionMember:
type: object
properties:
id:
type: string
status:
type: string
enum:
- JOINED
- INVITED
- LEFT
- CONNECTED
ItemPagedResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Item'
paging:
$ref: '#/components/schemas/Paging'
total:
type: integer
Item:
type: object
properties:
itemId:
type: string
namespace:
type: string
sku:
type: string
name:
type: string
itemType:
type: string
enum:
- APP
- COINS
- INGAMEITEM
- BUNDLE
- CODE
- SUBSCRIPTION
- SEASON
- MEDIA
- OPTIONBOX
regionData:
type: array
items:
$ref: '#/components/schemas/RegionPrice'
RegionPrice:
type: object
properties:
currencyCode:
type: string
currencyType:
type: string
enum:
- REAL
- VIRTUAL
price:
type: integer
discountedPrice:
type: integer
EntitlementPagedResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Entitlement'
paging:
$ref: '#/components/schemas/Paging'
Entitlement:
type: object
properties:
id:
type: string
namespace:
type: string
userId:
type: string
itemId:
type: string
sku:
type: string
status:
type: string
enum:
- ACTIVE
- INACTIVE
- CONSUMED
- REVOKED
useCount:
type: integer
OrderRequest:
type: object
properties:
itemId:
type: string
quantity:
type: integer
currencyCode:
type: string
price:
type: integer
region:
type: string
required:
- itemId
- quantity
Order:
type: object
properties:
orderNo:
type: string
userId:
type: string
itemId:
type: string
status:
type: string
enum:
- INIT
- CHARGED
- CHARGEBACK
- FULFILLED
- REFUNDED
- CLOSED
price:
type: integer
currency:
$ref: '#/components/schemas/RegionPrice'
Wallet:
type: object
properties:
id:
type: string
namespace:
type: string
userId:
type: string
currencyCode:
type: string
balance:
type: integer
status:
type: string
enum:
- ACTIVE
- INACTIVE
UserSeasonProgression:
type: object
properties:
seasonId:
type: string
userId:
type: string
currentTierIndex:
type: integer
currentExp:
type: integer
requiredExp:
type: integer
passes:
type: array
items:
type: string
UserAchievementPagedResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/UserAchievement'
paging:
$ref: '#/components/schemas/Paging'
UserAchievement:
type: object
properties:
achievementCode:
type: string
name:
type: string
status:
type: integer
description: 1 = in progress, 2 = unlocked.
latestValue:
type: number
achievedAt:
type: string
format: date-time
ClaimServerRequest:
type: object
properties:
session_id:
type: string
required:
- session_id
DedicatedServer:
type: object
properties:
pod_name:
type: string
namespace:
type: string
ip:
type: string
port:
type: integer
region:
type: string
status:
type: string
enum:
- CREATING
- READY
- BUSY
- REMOVING
TelemetryEvent:
type: object
properties:
EventNamespace:
type: string
EventName:
type: string
Payload:
type: object
additionalProperties: true
ClientTimestamp:
type: string
format: date-time
required:
- EventNamespace
- EventName
- Payload
CreateContentRequest:
type: object
properties:
name:
type: string
type:
type: string
subtype:
type: string
fileExtension:
type: string
tags:
type: array
items:
type: string
contentType:
type: string
required:
- name
- fileExtension
Content:
type: object
properties:
id:
type: string
namespace:
type: string
channelId:
type: string
name:
type: string
creatorName:
type: string
payloadUrl:
type: array
items:
type: object
properties:
url:
type: string
tags:
type: array
items:
type: string
isOfficial:
type: boolean