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