> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aegi.run/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aegi.run/_mcp/server.

# Minecraft

## Identifying a player

Every Minecraft route takes a `{player}` that accepts any of:

* a Java or Bedrock username (`Notch`)
* a Java UUID
* a Floodgate UUID, for Bedrock players
* an XUID, for Bedrock players

Bedrock accounts resolve through Geyser, so a Java name and its Bedrock
equivalent reach the same player.

## Player info

```
GET /v1/minecraft/info/{player}
```

```ts
const player = await aegis.minecraft.info('Notch')

player.id
player.name
player.platform // 'java' | 'bedrock'
player.slim // whether the skin uses the slim ("Alex") model
player.updatedAt
```

## Skin textures

```
GET /v1/minecraft/textures/{player}
```

Returns URLs, not pixels:

```ts
const textures = await aegis.minecraft.textures('Notch')

textures.skin // skin texture URL, or null
textures.cape // cape texture URL, or null
textures.slim
textures.hash
textures.updatedAt
```

A player with no stored skin answers `404`.

## Renders

```
GET /v1/minecraft/render/{player}
```

Rendering takes long enough that it is queued. This endpoint is the one place
in the API that answers `202` rather than `200`:

```ts
const render = await aegis.minecraft.render('Notch', {
  render: 'wave',
  scale: 2,
})

const { status, result } = await aegis.jobs.wait(render.jobId, { timeout: 60 })
```

| Parameter | Values                                                                                       | Default |
| --------- | -------------------------------------------------------------------------------------------- | ------- |
| `render`  | `head`, `body`, `front`, `wave`, `sit`, `handstand`, `cutesit`, `standing`, `showing_behind` | `wave`  |
| `scale`   | 1–4                                                                                          | `1`     |
| `skinUrl` | Any skin texture URL                                                                         | —       |
| `capeUrl` | Any cape texture URL                                                                         | —       |

Passing `skinUrl` renders that texture directly and **skips the player lookup
entirely**, which is how you render a skin for a player the API cannot resolve:

```ts
await aegis.minecraft.render('custom', {
  skinUrl: 'https://textures.minecraft.net/texture/abc123',
  render: 'standing',
})
```

## Errors

Minecraft routes are the only ones that can return `502`, because they talk to
upstream services:

| Status | Cause                                          |
| ------ | ---------------------------------------------- |
| `400`  | The identifier is malformed                    |
| `404`  | No such player, or no stored skin for textures |
| `502`  | The upstream Minecraft service failed          |

## Cost

Info and textures are `cheap`. Renders are `puppeteer` — the most expensive
class, and not included on the `free` plan. See [rate limits](/rate-limits).