---
url: https://milthm.cn/wiki/en/manual/developer/milkloud/profile.md
description: Read public and current-user profiles and update a nickname.
---

# Profile

The Profile API exposes a small public profile, scoped information about the authenticated user, and a nickname update.
It does not expose account administration or first-party game settings to third-party integrations.

## Read the Current User

```http
GET /v1/user
Accept: application/json
Authorization: Bearer ACCESS_TOKEN
```

The response data has this public shape:

```ts
export interface CurrentUserProfile {
  uid?: string;
  zone?: string;
  username?: string;
  nickname?: string;
  avatar?: string;
  email?: string;
}
```

Fields are optional and depend on the credential's granted scopes:

| Fields | Returned with |
|--------|---------------|
| `uid`, `zone` | Any of `openid`, `profile`, or `user` |
| `username`, `nickname`, `avatar` | Either `profile` or `user` |
| `email` | `email` |

Additional fields used by first-party clients are not part of this contract.

## Read a Public Profile

```http
GET /v1/user/:identity
Accept: application/json
```

This endpoint does not require authentication.

| Parameter | Location | Required | Default | Description |
|-----------|----------|----------|---------|-------------|
| `identity` | Path | Yes | None | A URL-encoded username or `UID:<uid>` as one URL-encoded path segment. |

The public response contains only these optional fields:

```ts
export interface PublicUserProfile {
  username?: string;
  nickname?: string;
  avatar?: string;
}
```

An authenticated request for the credential owner's own identity may return the expanded current-user shape according
to its scopes. Omit credentials when an integration specifically needs the stable public shape.

## Update the Nickname

```http
PATCH /v1/user
Accept: application/json
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
```

The credential must have the `user` scope. The read-only `profile` scope is not sufficient.

| Parameter | Location | Required | Default | Description |
|-----------|----------|----------|---------|-------------|
| `nickname` | Body | Yes | None | The new nickname. It must be non-empty. |

Example request:

```bash
curl \
  --request PATCH \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --data '{"nickname":"New Nickname"}' \
  'https://milkloud.milthm.com/api/v1/user'
```

A successful update returns the common envelope without `data`:

```json
{
  "code": "OK",
  "message": "OK"
}
```

Submitting a nickname change consumes one change opportunity, even if the change does not succeed. One opportunity
recovers every 15 days and 12 hours.

This API changes only the nickname.

## Errors

Authenticated profile requests may return the [common authentication errors](https://milthm.cn/wiki/en/manual/developer/milkloud/errors.md#authentication-errors).

| Operation | HTTP status | Code | Meaning |
|-----------|-------------|------|---------|
| Read public or current profile | `404` | `UserNotFoundError` | The identity does not exist or the account is no longer available. |
| Update nickname | `400` | `RequestParamError` | The request does not contain a supported non-empty update. |
| Update nickname | `409` | `UserNicknameTakenError` | The requested nickname is unavailable. |
| Update nickname | `409` | `StaminaNotEnough` | No nickname change opportunity is available. |