OpenAPI Specification
openapi: 3.0.3
info:
title: Minecraft Services Attributes Profile 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: Profile
description: Authenticated profile and name management
paths:
/minecraft/profile:
get:
operationId: getAuthenticatedProfile
summary: Get Authenticated Profile
description: Return the signed-in player's own profile including UUID, name, owned skins, and owned capes.
tags:
- Profile
security:
- bearerAuth: []
responses:
'200':
description: Authenticated profile.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticatedProfile'
'401':
description: Missing or invalid access token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/minecraft/profile/namechange:
get:
operationId: getNameChangeInfo
summary: Get Name Change Info
description: Returns the player's name-change cooldown state — last-change date, creation date, and whether a change is currently allowed.
tags:
- Profile
security:
- bearerAuth: []
responses:
'200':
description: Name-change information.
content:
application/json:
schema:
$ref: '#/components/schemas/NameChangeInfo'
'401':
description: Missing or invalid access token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/minecraft/profile/name/{name}/available:
get:
operationId: checkNameAvailability
summary: Check Name Availability
description: Check whether a desired username is available, duplicate, or otherwise not allowed. Rate-limited to roughly 20 requests per five minutes per account.
tags:
- Profile
security:
- bearerAuth: []
parameters:
- name: name
in: path
required: true
description: Candidate username.
example: NewName123
schema:
type: string
responses:
'200':
description: Availability response.
content:
application/json:
schema:
$ref: '#/components/schemas/NameAvailability'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/minecraft/profile/name/{name}:
put:
operationId: changeName
summary: Change Name
description: Change the authenticated player's username.
tags:
- Profile
security:
- bearerAuth: []
parameters:
- name: name
in: path
required: true
description: New username.
example: NewName123
schema:
type: string
responses:
'200':
description: Updated profile.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticatedProfile'
'400':
description: Invalid name supplied.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Name already taken or change not currently allowed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/user/profiles/{uuid}/names:
get:
operationId: getNameHistory
summary: Get Name History (Deprecated)
description: Returns the full name-change history for the player identified by UUID. Deprecated and disabled by Mojang on 13 September 2022 — the endpoint now returns 410 Gone for all callers. Documented for historical reference and archival research.
tags:
- Profile
deprecated: true
parameters:
- name: uuid
in: path
required: true
description: Player UUID (with or without hyphens).
example: 853c80ef3c3749fdaa49938b674adae6
schema:
type: string
pattern: ^[0-9a-fA-F-]{32,36}$
responses:
'200':
description: Historical response; no longer issued.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NameChange'
'410':
description: Endpoint disabled by Mojang.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_2'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orders/statistics:
post:
operationId: getSaleStatistics
summary: Get Sale Statistics
description: Returns aggregate sale and revenue statistics across one or more Mojang product SKUs (Minecraft, Minecraft Realms, Minecraft Bedrock, Cobalt, etc.). Public, unauthenticated.
tags:
- Profile
requestBody:
required: true
description: SKU filter.
content:
application/json:
schema:
$ref: '#/components/schemas/SaleStatisticsRequest'
responses:
'200':
description: Aggregate sale statistics.
content:
application/json:
schema:
$ref: '#/components/schemas/SaleStatistics'
'400':
description: Invalid metric key supplied.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_2'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
NameAvailability:
type: object
description: Response from the name-availability check.
required:
- status
properties:
status:
type: string
enum:
- AVAILABLE
- DUPLICATE
- NOT_ALLOWED
example: AVAILABLE
NameChange:
type: object
description: A historical name-change entry (deprecated endpoint).
required:
- name
properties:
name:
type: string
description: Player username at the time of the change.
example: jeb_
changedToAt:
type: integer
format: int64
description: Unix epoch milliseconds at which the player changed to this name. Absent for the original account name.
example: 1417597263000
SaleStatistics:
type: object
description: Aggregate sale figures.
properties:
total:
type: integer
description: Total units sold across the requested SKUs.
example: 41000000
last24h:
type: integer
description: Units sold in the last 24 hours.
example: 75000
saleVelocityPerSeconds:
type: number
format: float
description: Recent average sales per second.
example: 0.85
SaleStatisticsRequest:
type: object
description: Filter for the /orders/statistics request.
required:
- metricKeys
properties:
metricKeys:
type: array
description: SKUs to aggregate.
items:
type: string
enum:
- item_sold_minecraft
- prepaid_card_redeemed_minecraft
- item_sold_cobalt
- item_sold_scrolls
- item_sold_dungeons
example:
- item_sold_minecraft
- prepaid_card_redeemed_minecraft
Error:
type: object
description: Standard Minecraft Services error envelope.
properties:
path:
type: string
description: Request path that produced the error.
example: /minecraft/profile/lookup/name/zzzzzzzzzzzzzz
errorType:
type: string
description: Mojang error class.
example: NOT_FOUND
error:
type: string
description: Short error name.
example: NOT_FOUND
errorMessage:
type: string
description: Human-readable description.
example: Couldn't find any profile with name zzzzzzzzzzzzzz
developerMessage:
type: string
description: Optional developer-facing message.
example: Couldn't find any profile with name zzzzzzzzzzzzzz
NameChangeInfo:
type: object
description: Name-change cooldown information.
properties:
changedAt:
type: string
format: date-time
description: ISO 8601 timestamp of the most recent name change.
example: '2025-04-12T18:30:00Z'
createdAt:
type: string
format: date-time
description: ISO 8601 timestamp of the player profile's creation.
example: '2014-11-19T12:42:43Z'
nameChangeAllowed:
type: boolean
description: True if a name change is currently allowed.
example: true
Cape:
type: object
description: A cape owned by the authenticated player.
required:
- id
- state
- url
properties:
id:
type: string
description: Cape UUID.
example: 1981aad373fa9754
state:
type: string
enum:
- ACTIVE
- INACTIVE
example: ACTIVE
url:
type: string
format: uri
description: Cape texture URL.
example: https://textures.minecraft.net/texture/cape123...
alias:
type: string
description: Cape display name.
example: Migrator
AuthenticatedProfile:
type: object
description: The authenticated player's own profile with skins and capes.
required:
- id
- name
properties:
id:
type: string
description: Player UUID without hyphens.
example: 853c80ef3c3749fdaa49938b674adae6
name:
type: string
description: Current username.
example: jeb_
skins:
type: array
description: All skins owned by the player; one is marked ACTIVE.
items:
$ref: '#/components/schemas/Skin'
capes:
type: array
description: All capes owned by the player; one may be marked ACTIVE.
items:
$ref: '#/components/schemas/Cape'
profileActions:
type: array
description: Sanctions in effect on the profile (e.g. FORCED_NAME_CHANGE).
items:
type: string
example: []
Skin:
type: object
description: A skin owned by the authenticated player.
required:
- id
- state
- url
- variant
properties:
id:
type: string
description: Skin UUID.
example: cd9a82a0-0b9c-4f10-8c2a-1b1f87b2af80
state:
type: string
enum:
- ACTIVE
- INACTIVE
example: ACTIVE
url:
type: string
format: uri
description: Texture URL.
example: https://textures.minecraft.net/texture/abc123...
textureKey:
type: string
description: Texture content hash.
example: abc123def456...
variant:
type: string
enum:
- CLASSIC
- SLIM
example: CLASSIC
alias:
type: string
description: Skin alias / nickname.
example: Steve
Error_2:
type: object
description: Standard Mojang error envelope.
properties:
error:
type: string
description: Error class name.
example: IllegalArgumentException
errorMessage:
type: string
description: Human-readable error description.
example: Path /users/profiles/minecraft/ is invalid.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Minecraft access token issued by /authentication/login_with_xbox. Used as `Authorization: Bearer {token}`.'