openapi: 3.0.3
info:
  title: Minecraft Services Attributes Textures API
  description: Microsoft-managed Minecraft Services API (api.minecraftservices.com). Covers authenticated player profile management, name change, skin and cape management, player attributes (chat, friends, profanity filter), privacy blocklist, friends graph, presence reporting, signature keypair issuance, public-key publication for chat signature verification, and player entitlement / ownership checks. Most endpoints require a Minecraft Bearer access token obtained via the Xbox Live -> XSTS -> Minecraft authentication chain.
  version: 1.0.0
  contact:
    name: Mojang Studios
    url: https://www.minecraft.net
  license:
    name: Mojang Brand and Asset Usage Guidelines
    url: https://www.minecraft.net/en-us/usage-guidelines
  x-generated-from: documentation
  x-last-validated: '2026-05-30'
servers:
- url: https://api.minecraftservices.com
  description: Microsoft / Minecraft Services API (production)
security: []
tags:
- name: Textures
  description: Player skin and cape texture lookup
paths:
  /session/minecraft/profile/{uuid}:
    get:
      operationId: getSessionProfile
      summary: Get Session Profile (Skin and Cape)
      description: Returns the player's session profile including the Base64-encoded textures property holding skin and cape URLs. Pass unsigned=false to receive a signed payload that includes Mojang's RSA signature.
      tags:
      - Textures
      parameters:
      - name: uuid
        in: path
        required: true
        description: Player UUID (hyphenated or unhyphenated).
        example: 853c80ef3c3749fdaa49938b674adae6
        schema:
          type: string
          pattern: ^[0-9a-fA-F-]{32,36}$
      - name: unsigned
        in: query
        required: false
        description: Set to false to include the Mojang signature on each property. When omitted, properties are returned without signature.
        example: false
        schema:
          type: boolean
      responses:
        '200':
          description: Session profile with textures property.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionProfile'
        '204':
          description: UUID has no matching profile.
        '400':
          description: UUID parameter is not a valid Minecraft UUID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (per-IP).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    SessionProfile:
      type: object
      description: A signed session profile with textures and metadata properties.
      required:
      - id
      - name
      - properties
      properties:
        id:
          type: string
          description: Player UUID without hyphens.
          example: 853c80ef3c3749fdaa49938b674adae6
        name:
          type: string
          description: Player username.
          example: jeb_
        properties:
          type: array
          description: Signed property list (currently only `textures`).
          items:
            $ref: '#/components/schemas/SessionProperty'
        profileActions:
          type: array
          description: Sanctions or actions Mojang has taken on the profile.
          items:
            type: string
            example: FORCED_NAME_CHANGE
    SessionProperty:
      type: object
      description: A single signed session-profile property (e.g. textures).
      required:
      - name
      - value
      properties:
        name:
          type: string
          description: Property name (typically `textures`).
          example: textures
        value:
          type: string
          description: Base64-encoded JSON payload (skin / cape URLs and metadata).
          example: ewogICJ0aW1lc3RhbXAiIDogMTcwMDAwMDAwMDAwMCwKICAicHJvZmlsZUlkIiA6IC4uLgp9
        signature:
          type: string
          description: Mojang RSA signature of `value`. Present only when the request included `unsigned=false`.
          example: a1b2c3d4...==
    Error:
      type: object
      description: Standard Mojang error envelope.
      properties:
        error:
          type: string
          description: Error class name.
          example: ForbiddenOperationException
        errorMessage:
          type: string
          description: Human-readable error description.
          example: Invalid token.
        cause:
          type: string
          description: Optional cause classification.
          example: UserMigratedException
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Minecraft access token issued by /authentication/login_with_xbox. Used as `Authorization: Bearer {token}`.'