API Evangelist enhancements for the Kongregate Server-Side API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Kongregate Server-Side API
  version: 1.0.0
extends: openapi/kongregate-server-api-openapi-original.json
x-generated: '2026-07-19'
x-method: generated
x-source: >-
  Derived from openapi/kongregate-server-api-openapi-original.json plus the Kongregate developer
  documentation at https://docs.kongregate.com/. This overlay records API Evangelist
  enhancements only — the harvested original specification is never mutated.
actions:

- target: $.info
  description: Give the specification a real title, contact and licence identity.
  update:
    title: Kongregate Server-Side API
    description: >-
      Server-side REST API for games hosted on the Kongregate platform. Covers player
      authentication, statistics and leaderboards, the Kreds virtual-goods catalogue and
      inventory, guilds and characters, Kongpanions, and shared links. All calls are
      authenticated with a private per-game API key, which must never be used from a game
      client.
    contact:
      name: Kongregate Developer Support
      url: https://kongregatesupport.zendesk.com/hc/en-us/categories/26688218392717-Developers
    termsOfService: https://www.kongregate.com/en/terms-of-service
    x-apievangelist-enriched: '2026-07-19'
    x-logo:
      url: https://www.kongregate.com

- target: $
  description: >-
    Declare the security schemes the API actually uses. The published specification ships an
    EMPTY components.securitySchemes object even though every operation requires an api_key,
    so no tooling can generate correct authenticated clients from it as published.
  update:
    externalDocs:
      description: Kongregate Developers documentation
      url: https://docs.kongregate.com/
    tags:
    - name: Authentication
      description: Exchange a client-minted game_auth_token for the player's identity.
    - name: Statistics
      description: Submit statistics and read lifetime, weekly, daily and friends leaderboards.
    - name: Items
      description: The Kreds virtual-goods catalogue, per-user inventory, and item consumption.
    - name: Guilds
      description: Game-defined player groups and the characters that belong to them.
    - name: Kongpanions
      description: Platform-level collectibles and a user's collection.
    - name: Shared Links
      description: Expiring shareable links generated from inside a game.
    - name: Users
      description: Player profile, friends and mute lists.

- target: $.components
  description: Add the api_key and game_auth_token security schemes missing from the original.
  update:
    securitySchemes:
      apiKeyQuery:
        type: apiKey
        in: query
        name: api_key
        description: >-
          Private per-game API key, retrieved from the game's own /api page at
          https://www.kongregate.com/games/{username}/{game}/api. Server-side only — never
          expose this in game client code.

- target: $.servers
  description: Document that there is no separate sandbox host.
  update:
  - url: https://api.kongregate.com/api
    description: >-
      Production. Kongregate publishes no sandbox host; testing runs against production,
      isolated by game preview state and by developer accounts that transact at zero Kreds.

- target: $.paths['/authenticate.json'].get
  description: >-
    Flag the status-code decoupling. Both documented failure modes are returned as HTTP 200
    with success:false in the body, which silently breaks clients that branch on HTTP status.
  update:
    tags: [Authentication]
    x-apievangelist-notes:
      status_code_decoupled: true
      warning: >-
        Invalid Credentials (error 403) and Bad Parameters (error 400) are both returned as
        HTTP 200. Branch on the response body's `success` boolean, not on the HTTP status.
      token_rotation: >-
        game_auth_token changes whenever the player changes their password. Treat a 403 as a
        signal to re-fetch the token client-side rather than as a permanent failure.

- target: $.paths['/use_item.json'].post
  description: Flag the non-idempotent consume operation.
  update:
    tags: [Items]
    x-apievangelist-notes:
      idempotent: false
      warning: >-
        Consuming an item decrements remaining_uses. Kongregate documents no idempotency key,
        so a retry after a network timeout can double-consume. Reconcile against the returned
        usage_record_id and remaining_uses, or re-read the inventory via /user_items.json,
        before retrying.
      error_schema_missing: >-
        The declared 400 response carries no schema and no body, so failures are not
        machine-readable.

- target: $.paths['/submit_statistics.json'].post
  description: Record the statistic-type semantics that determine retry safety.
  update:
    tags: [Statistics]
    x-apievangelist-notes:
      idempotent: conditional
      detail: >-
        Statistic type determines retry safety. max, min and replace statistics are naturally
        idempotent — resubmitting the same value is a no-op, which is why the documentation
        recommends resubmitting all data retroactively on game load. "add" statistics accumulate
        and are NOT safe to retry.
      constraints: >-
        Statistic values must be non-negative integers with a maximum of BIG_INT (9.223e18).
        Sub-integer values must be scaled (e.g. seconds to milliseconds) before submission.

- target: $.paths['/high_scores/{scope}/:statistic_id.json'].get
  description: Note the malformed path template in the published specification.
  update:
    tags: [Statistics]
    x-apievangelist-notes:
      spec_defect: >-
        The path mixes two templating styles: {scope} is OpenAPI-style while :statistic_id is
        Rails-style. Generated clients will not substitute :statistic_id. The same defect
        appears on /high_scores/friends/{statistic_id}/:user_id.json.

- target: $.paths['/high_scores/friends/{statistic_id}/:user_id.json'].get
  description: Tag and flag the same path-template defect.
  update:
    tags: [Statistics]
    x-apievangelist-notes:
      spec_defect: >-
        :user_id uses Rails-style templating rather than OpenAPI {user_id} and will not be
        substituted by generated clients.

- target: $.paths['/items.json'].get
  update:
    tags: [Items]

- target: $.paths['/user_items.json'].get
  update:
    tags: [Items]

- target: $.paths['/guilds.json'].post
  update:
    tags: [Guilds]

- target: $.paths['/guilds/destroy.json'].post
  update:
    tags: [Guilds]
    x-apievangelist-notes:
      destructive: true
      warning: Unrecoverable. Gate behind explicit confirmation in any agent-driven caller.

- target: $.paths['/characters.json'].post
  update:
    tags: [Guilds]

- target: $.paths['/kongpanions/index.json'].get
  update:
    tags: [Kongpanions]

- target: $.paths['/kongpanions.json'].get
  update:
    tags: [Kongpanions]

- target: $.paths['/shared_links/create.json'].post
  update:
    tags: [Shared Links]

- target: $.paths['/shared_links/{id}/destroy.json'].post
  update:
    tags: [Shared Links]
    x-apievangelist-notes:
      destructive: true

- target: $.paths['/user_info.json'].get
  update:
    tags: [Users]
    x-apievangelist-notes:
      batching: >-
        Accepts plural usernames / user_ids for multi-user lookup alongside the singular forms.
      expansion: >-
        Setting `friends` expands the response with friends, friend_ids, muted_users and
        muted_user_ids.