steamgpt-net Profile API

openapi: 3.2.0
info:
  title: SteamGPT Profile API
  version: 1.3.0
  description: Structured Steam identity and gaming context API, designed for AI agents and search assistants that need factual public Steam player information. No auth, no cookies, no tracking. Append .md (markdown), .json (JSON) or .ai (deterministic plain text) to any data endpoint; default depends on Accept header. Errors carry a machine-readable `error` slug and follow the same format selection.
servers:
- url: https://steamgpt.net
- url: https://steamgpt.net/v1
security:
- {}
- boostToken:
  - rate-boost
tags:
- name: Profile
paths:
  /profile/{id}:
    get:
      summary: Use when only the raw Steam profile is needed.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: steamid64 (17 digits), STEAM_1:0:x, [U:1:x], steamcommunity.com profile URL or vanity name
      responses:
        '200':
          description: Steam summary only
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
            text/markdown:
              schema:
                type: string
            text/plain:
              schema:
                type: string
              description: .ai deterministic text
            text/html:
              schema:
                type: string
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited, honor Retry-After
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Profile
      operationId: getProfileById
      x-operation-id-source: derived
components:
  schemas:
    Profile:
      type: object
      properties:
        result:
          type: string
          enum:
          - success
        data:
          $ref: '#/components/schemas/ProfileData'
    Canonical:
      type: object
      description: 'Stable resource identity: vanity and steamid64 URLs are the same resource'
      properties:
        steamid64:
          type: string
        url:
          type: string
    SteamPlayer:
      type:
      - object
      - 'null'
      description: Raw Steam GetPlayerSummaries player object, unmodified field names
      properties:
        steamid:
          type: string
        personaname:
          type: string
        profileurl:
          type: string
        avatar:
          type: string
        avatarmedium:
          type: string
        avatarfull:
          type: string
        personastate:
          type: integer
          description: 0 offline, 1 online, 2 busy, 3 away, 4 snooze, 5 looking to trade, 6 looking to play
        communityvisibilitystate:
          type: integer
          description: 3 = public
        timecreated:
          type: integer
          description: unixtime
        lastlogoff:
          type: integer
          description: unixtime
        gameextrainfo:
          type: string
        loccountrycode:
          type: string
      additionalProperties: true
    ProfileData:
      type: object
      properties:
        steamid64:
          type: string
        ids:
          $ref: '#/components/schemas/Ids'
        steam:
          $ref: '#/components/schemas/SteamPlayer'
        canonical:
          $ref: '#/components/schemas/Canonical'
        provenance:
          type: object
          properties:
            steam:
              $ref: '#/components/schemas/SourceProvenance'
    SourceProvenance:
      type: object
      properties:
        source:
          type: string
          example: Steam Web API
        retrieved_at:
          type:
          - integer
          - 'null'
          description: unixtime of the cached snapshot
        age_seconds:
          type:
          - integer
          - 'null'
          description: snapshot age at response time
        fresh:
          type: boolean
          description: age within cache_ttl; false when unknown
        cache_ttl:
          type:
          - integer
          - 'null'
          description: refresh policy in seconds
        refreshed_with:
          type: string
          description: 'steam_bans only: bans refresh together with this source snapshot'
    Error:
      type: object
      properties:
        result:
          type: string
          enum:
          - error
        code:
          type: integer
        error:
          type: string
          enum:
          - player_not_found
          - no_faceit_data
          - no_bans_data
          - batch_too_large
          - batch_no_valid_ids
          - bad_request
          - invalid_token
          - unknown_endpoint
          - rate_limited
          - internal
        message:
          type: string
      required:
      - result
      - code
      - error
    Ids:
      type: object
      description: All SteamID representations of the player
      properties:
        steamid64:
          type: string
          example: '76561197960287930'
        steamid:
          type:
          - string
          - 'null'
          example: STEAM_1:0:11101
        steamid3:
          type:
          - string
          - 'null'
          example: '[U:1:22202]'
  securitySchemes:
    boostToken:
      type: oauth2
      description: 'OPTIONAL. Every endpoint works without any credential. A self-service token (no registration, no client_id) raises the per-IP rate limit from 120 to 600 requests/min. Send it as: Authorization: Bearer <access_token>. Details: https://steamgpt.net/auth.md'
      flows:
        clientCredentials:
          tokenUrl: https://steamgpt.net/oauth/token
          scopes:
            rate-boost: Higher per-IP rate limit (600/min instead of 120/min)