openapi: 3.0.3
info:
  title: GameAnalytics REST APIs Collection API
  description: 'Representative OpenAPI description of the public GameAnalytics REST surfaces: the Collection (Collector) API for HMAC-signed event ingestion, the Metrics API for aggregated reporting, and the Organization API for programmatic administration of games, studios, users, and permissions. Endpoints and authentication reflect the public GameAnalytics documentation; consult the docs for the full request/response payloads, which are large and evolving.'
  termsOfService: https://gameanalytics.com/terms/
  contact:
    name: GameAnalytics Support
    url: https://gameanalytics.com/contact/
  version: '1.0'
servers:
- url: https://api.gameanalytics.com
  description: Collection API - production
- url: https://sandbox-api.gameanalytics.com
  description: Collection API - sandbox
- url: https://metrics.gameanalytics.com
  description: Metrics API
- url: https://organization.gameanalytics.com
  description: Organization API
tags:
- name: Collection
  description: HMAC-signed event ingestion (Collector API).
paths:
  /v2/{game_key}/init:
    post:
      operationId: collectionInit
      tags:
      - Collection
      summary: Initialize an SDK/collection session.
      description: Returns a server timestamp and an `enabled` flag before events are sent. The request body must be signed with an HMAC-SHA256 digest of the raw (optionally gzipped) body using the game secret key, base64-encoded, and supplied in the `Authorization` header. HTTPS is required.
      security:
      - hmacAuth: []
      parameters:
      - $ref: '#/components/parameters/GameKey'
      - $ref: '#/components/parameters/ContentEncoding'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitRequest'
      responses:
        '200':
          description: Initialization succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/{game_key}/events:
    post:
      operationId: collectionEvents
      tags:
      - Collection
      summary: Submit a batch of game events.
      description: Accepts a JSON array of event objects (categories include `user`, `session_end`, `business`, `resource`, `progression`, `design`, `error`, and `ads`). The gzipped body must be signed with an HMAC-SHA256 digest using the game secret key (base64) in the `Authorization` header. POST size limit is 1 MB; gzip is strongly recommended.
      security:
      - hmacAuth: []
      parameters:
      - $ref: '#/components/parameters/GameKey'
      - $ref: '#/components/parameters/ContentEncoding'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: Events accepted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          description: Payload exceeds the 1 MB POST size limit.
components:
  parameters:
    ContentEncoding:
      name: Content-Encoding
      in: header
      required: false
      description: Set to `gzip` when the body is gzip-compressed (strongly recommended).
      schema:
        type: string
        enum:
        - gzip
    GameKey:
      name: game_key
      in: path
      required: true
      description: The public game key identifying the game in GameAnalytics.
      schema:
        type: string
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    InitResponse:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether event collection is enabled for this game.
        server_ts:
          type: integer
          format: int64
          description: Server-side Unix timestamp used to correct client clocks.
    InitRequest:
      type: object
      properties:
        platform:
          type: string
          example: ios
        os_version:
          type: string
          example: ios 17.0
        sdk_version:
          type: string
          example: rest api v2
    Event:
      type: object
      description: A single GameAnalytics event. The `category` field determines which additional fields are required. See the Collection API docs for the full set of fields per category.
      required:
      - category
      properties:
        category:
          type: string
          enum:
          - user
          - session_end
          - business
          - resource
          - progression
          - design
          - error
          - ads
          description: The event category.
        v:
          type: integer
          example: 2
        user_id:
          type: string
        session_id:
          type: string
        session_num:
          type: integer
        client_ts:
          type: integer
          format: int64
        sdk_version:
          type: string
        os_version:
          type: string
        manufacturer:
          type: string
        device:
          type: string
        platform:
          type: string
        build:
          type: string
        event_id:
          type: string
          description: For design/progression/resource events, the hierarchical event identifier.
        amount:
          type: number
          description: For business/resource events, the transaction or resource amount.
        currency:
          type: string
          description: For business events, the ISO 4217 currency code.
        value:
          type: number
          description: For design events, an optional numeric value.
  responses:
    Unauthorized:
      description: Missing or invalid authentication (bad HMAC signature or API key).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    hmacAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Base64-encoded HMAC-SHA256 digest of the raw (optionally gzipped) request body, keyed with the game's secret key. Used by the Collection API.
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key generated in the GameAnalytics dashboard. The Metrics API uses the `X-API-Key` header; the Organization API uses an equivalent API-key header.