### Event Push: SSE Connection Request (HTTP)

Source: https://milky.ntqqrev.org/guide/communication

Example of an HTTP GET request to establish a Server-Sent Events (SSE) connection for receiving events. It includes an Authorization header for security.

```http
GET /event
Authorization: Bearer 123456
```

--------------------------------

### API Response: Success Example (JSON)

Source: https://milky.ntqqrev.org/guide/communication

Example of a successful API response from the Milky protocol. It includes a status, a success retcode (0), and a data object containing relevant information.

```json
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "message_seq": 23333,
    "time": 1234567890
  }
}
```

--------------------------------

### System API: Get User Profile

Source: https://milky.ntqqrev.org/api/system

Retrieves the profile information for a specified user ID.

```APIDOC
## GET /get_user_profile

### Description
Retrieves the profile information for a specified user ID.

### Method
GET

### Endpoint
/get_user_profile

### Parameters
#### Path Parameters
None

#### Query Parameters
- **user_id** (int64) - Required - The QQ number of the user.

#### Request Body
None

### Request Example
```json
{
  "user_id": 987654321
}
```

### Response
#### Success Response (200)
- **nickname** (string) - The nickname of the user.
- **qid** (string) - The QID of the user.
- **age** (int32) - The age of the user.
- **sex** (enum) - The sex of the user. Possible values: `male`, `female`, `unknown`.
- **remark** (string) - The remark for the user.
- **bio** (string) - The personal signature of the user.
- **level** (int32) - The QQ level of the user.
- **country** (string) - The country or region of the user.
- **city** (string) - The city of the user.
- **school** (string) - The school of the user.

#### Response Example
```json
{
  "nickname": "AnotherUser",
  "qid": "some_qid",
  "age": 25,
  "sex": "male",
  "remark": "Friend",
  "bio": "Hello there!",
  "level": 10,
  "country": "USA",
  "city": "New York",
  "school": "Example University"
}
```
```

--------------------------------

### Get Impl Info API

Source: https://milky.ntqqrev.org/preview_path=kotlin%2Fkotlinx-serialization.txt

Retrieves information about the QQ protocol implementation.

```APIDOC
## GET /get_impl_info

### Description
Retrieves information about the QQ protocol implementation.

### Method
GET

### Endpoint
/get_impl_info

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **data** (object) - Implementation details.

#### Response Example
```json
{
  "data": {
    "impl": "NTQQ",
    "version": "1.0.0"
  }
}
```
```

--------------------------------

### System API: Get Cookies

Source: https://milky.ntqqrev.org/api/system

Retrieves the cookies associated with a specified domain.

```APIDOC
## GET /get_cookies

### Description
Retrieves the cookies associated with a specified domain.

### Method
GET

### Endpoint
/get_cookies

### Parameters
#### Path Parameters
None

#### Query Parameters
- **domain** (string) - Required - The domain for which to retrieve cookies.

#### Request Body
None

### Request Example
```json
{
  "domain": "example.com"
}
```

### Response
#### Success Response (200)
- **cookies** (string) - The cookie string for the specified domain.

#### Response Example
```json
{
  "cookies": "sessionid=abc123xyz; user=testuser"
}
```
```

--------------------------------

### System API: Get Friend Info

Source: https://milky.ntqqrev.org/api/system

Retrieves detailed information for a specific friend.

```APIDOC
## GET /get_friend_info

### Description
Retrieves detailed information for a specific friend.

### Method
GET

### Endpoint
/get_friend_info

### Parameters
#### Path Parameters
None

#### Query Parameters
- **user_id** (int64) - Required - The QQ number of the friend.
- **no_cache** (boolean) - Optional - Whether to force not using the cache. Defaults to `false`.

#### Request Body
None

### Request Example
```json
{
  "user_id": 333333333,
  "no_cache": false
}
```

### Response
#### Success Response (200)
- **friend** (FriendEntity) - The friend entity containing detailed information.

#### Response Example
```json
{
  "friend": {
    "user_id": 333333333,
    "nickname": "Friend3",
    "remark": "Buddy",
    "bio": "Best wishes!"
  }
}
```
```

--------------------------------

### System API: Get Group Info

Source: https://milky.ntqqrev.org/api/system

Retrieves detailed information for a specific group.

```APIDOC
## GET /get_group_info

### Description
Retrieves detailed information for a specific group.

### Method
GET

### Endpoint
/get_group_info

### Parameters
#### Path Parameters
None

#### Query Parameters
- **group_id** (int64) - Required - The group ID.
- **no_cache** (boolean) - Optional - Whether to force not using the cache. Defaults to `false`.

#### Request Body
None

### Request Example
```json
{
  "group_id": 100000003,
  "no_cache": false
}
```

### Response
#### Success Response (200)
- **group** (GroupEntity) - The group entity containing detailed information.

#### Response Example
```json
{
  "group": {
    "group_id": 100000003,
    "group_name": "Special Group",
    "owner_id": 444444444
  }
}
```
```

--------------------------------

### System API: Get CSRF Token

Source: https://milky.ntqqrev.org/api/system

Retrieves a CSRF (Cross-Site Request Forgery) token.

```APIDOC
## GET /get_csrf_token

### Description
Retrieves a CSRF (Cross-Site Request Forgery) token.

### Method
GET

### Endpoint
/get_csrf_token

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **csrf_token** (string) - The CSRF token.

#### Response Example
```json
{
  "csrf_token": "a_very_secure_csrf_token_value"
}
```
```

--------------------------------

### Get Implementation Info API

Source: https://milky.ntqqrev.org/preview_path=dart%2Fjson_serializable.txt

Retrieves information about the current QQ implementation.

```APIDOC
## GET /get_impl_info

### Description
Retrieves information about the current QQ implementation.

### Method
GET

### Endpoint
/get_impl_info

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **platform** (string) - The platform of the QQ implementation.
- **version** (string) - The version of the QQ implementation.

#### Response Example
```json
{
  "platform": "Windows",
  "version": "9.9.9"
}
```
```

--------------------------------

### System API: Get Friend List

Source: https://milky.ntqqrev.org/api/system

Retrieves the list of friends for the current QQ account. Supports cache control.

```APIDOC
## GET /get_friend_list

### Description
Retrieves the list of friends for the current QQ account. Supports cache control.

### Method
GET

### Endpoint
/get_friend_list

### Parameters
#### Path Parameters
None

#### Query Parameters
- **no_cache** (boolean) - Optional - Whether to force not using the cache. Defaults to `false`.

#### Request Body
None

### Request Example
```json
{
  "no_cache": true
}
```

### Response
#### Success Response (200)
- **friends** (FriendEntity[]) - An array of friend entities.

#### Response Example
```json
{
  "friends": [
    {
      "user_id": 111111111,
      "nickname": "Friend1"
    },
    {
      "user_id": 222222222,
      "nickname": "Friend2"
    }
  ]
}
```
```

--------------------------------

### System API: Get Custom Face URL List

Source: https://milky.ntqqrev.org/api/system

Retrieves a list of URLs for custom face (emoji) images.

```APIDOC
## GET /get_custom_face_url_list

### Description
Retrieves a list of URLs for custom face (emoji) images.

### Method
GET

### Endpoint
/get_custom_face_url_list

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **urls** (string[]) - A list of URLs for custom face images.

#### Response Example
```json
{
  "urls": [
    "http://example.com/face1.gif",
    "http://example.com/face2.png"
  ]
}
```
```

--------------------------------

### Get Login Info API

Source: https://milky.ntqqrev.org/preview_path=kotlin%2Fkotlinx-serialization.txt

Retrieves information about the current login session.

```APIDOC
## GET /get_login_info

### Description
Retrieves information about the current login session.

### Method
GET

### Endpoint
/get_login_info

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **data** (object) - Login information details.

#### Response Example
```json
{
  "data": {
    "user_id": 123456789,
    "nickname": "ExampleUser"
  }
}
```
```

--------------------------------

### Get User Profile API

Source: https://milky.ntqqrev.org/preview_path=kotlin%2Fkotlinx-serialization.txt

Retrieves the profile information for a given user.

```APIDOC
## GET /get_user_profile

### Description
Retrieves the profile information for a given user.

### Method
GET

### Endpoint
/get_user_profile

### Parameters
#### Query Parameters
- **user_id** (long) - Required - The ID of the user whose profile to retrieve.

#### Request Body
None

### Response
#### Success Response (200)
- **data** (object) - User profile details.

#### Response Example
```json
{
  "data": {
    "user_id": 123456789,
    "nickname": "ExampleUser",
    "avatar_url": "http://example.com/avatar.png"
  }
}
```
```

--------------------------------

### Get Cookies API

Source: https://milky.ntqqrev.org/preview_path=kotlin%2Fkotlinx-serialization.txt

Retrieves the cookies associated with the current QQ session.

```APIDOC
## GET /get_cookies

### Description
Retrieves the cookies associated with the current QQ session.

### Method
GET

### Endpoint
/get_cookies

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **data** (string) - The cookie string.

#### Response Example
```json
{
  "data": "sessionid=abcdef12345; othercookie=value"
}
```
```

--------------------------------

### Get Login Info API

Source: https://milky.ntqqrev.org/preview_path=dart%2Fjson_serializable.txt

Retrieves the login information for the current QQ account.

```APIDOC
## GET /get_login_info

### Description
Retrieves the login information for the current QQ account.

### Method
GET

### Endpoint
/get_login_info

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **user_id** (string) - The user ID of the logged-in account.
- **nickname** (string) - The nickname of the logged-in account.

#### Response Example
```json
{
  "user_id": "123456789",
  "nickname": "ExampleUser"
}
```
```

--------------------------------

### Get History Messages API

Source: https://milky.ntqqrev.org/preview_path=openapi%2Fopenapi.json

Fetches a list of historical messages for a given scene and peer ID. You can specify a starting message sequence and a limit for the number of messages to retrieve.

```APIDOC
## POST /get_history_messages

### Description
Retrieves a list of historical messages for a specified scene and peer ID.

### Method
POST

### Endpoint
/get_history_messages

### Parameters
#### Request Body
- **message_scene** (string) - Required - The scene of the messages (friend, group, temp).
- **peer_id** (integer) - Required - The QQ number of the friend or group number.
- **start_message_seq** (integer) - Optional - The starting message sequence number to query from (newest to oldest). If not provided, starts from the latest message.
- **limit** (integer) - Optional - The desired number of messages to retrieve, maximum 30. Defaults to 20.

### Response
#### Success Response (200)
- **messages** (array) - An array of message objects, each conforming to the IncomingMessage schema.
```

--------------------------------

### System API: Get Implementation Info

Source: https://milky.ntqqrev.org/api/system

Retrieves information about the protocol implementation, including version details and supported QQ protocol versions.

```APIDOC
## GET /get_impl_info

### Description
Retrieves information about the protocol implementation, including version details and supported QQ protocol versions.

### Method
GET

### Endpoint
/get_impl_info

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **impl_name** (string) - The name of the protocol implementation.
- **impl_version** (string) - The version of the protocol implementation.
- **qq_protocol_version** (string) - The QQ protocol version used by the implementation.
- **qq_protocol_type** (enum) - The platform of the QQ protocol used by the implementation. Possible values: `windows`, `linux`, `macos`, `android_pad`, `android_phone`, `ipad`, `iphone`, `harmony`, `watch`.
- **milky_version** (string) - The Milky protocol version implemented by the protocol implementation. Currently "1.1".

#### Response Example
```json
{
  "impl_name": "Milky",
  "impl_version": "1.1",
  "qq_protocol_version": "8.9.65",
  "qq_protocol_type": "windows",
  "milky_version": "1.1"
}
```
```

--------------------------------

### System API: Get Login Info

Source: https://milky.ntqqrev.org/api/system

Retrieves the login information for the current QQ account, including the user ID and nickname.

```APIDOC
## GET /get_login_info

### Description
Retrieves the login information for the current QQ account, including the user ID and nickname.

### Method
GET

### Endpoint
/get_login_info

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **uin** (int64) - The logged-in QQ number.
- **nickname** (string) - The logged-in nickname.

#### Response Example
```json
{
  "uin": 123456789,
  "nickname": "ExampleUser"
}
```
```

--------------------------------

### System API: Set Nickname

Source: https://milky.ntqqrev.org/api/system

Sets a new nickname for the QQ account.

```APIDOC
## POST /set_nickname

### Description
Sets a new nickname for the QQ account.

### Method
POST

### Endpoint
/set_nickname

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **new_nickname** (string) - Required - The new nickname for the QQ account.

### Request Example
```json
{
  "new_nickname": "New Awesome Name"
}
```

### Response
#### Success Response (200)
- This API has no output parameters.

#### Response Example
```json
{}
```
```

--------------------------------

### System API: Set Avatar

Source: https://milky.ntqqrev.org/api/system

Sets the QQ account avatar using a provided URI.

```APIDOC
## POST /set_avatar

### Description
Sets the QQ account avatar using a provided URI.

### Method
POST

### Endpoint
/set_avatar

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **uri** (string) - Required - The URI of the avatar file. Supports `file://`, `http(s)://`, and `base64://` formats.

### Request Example
```json
{
  "uri": "file:///path/to/avatar.png"
}
```

### Response
#### Success Response (200)
- This API has no output parameters.

#### Response Example
```json
{}
```
```

--------------------------------

### Get Friend List

Source: https://milky.ntqqrev.org/preview_path=milky-ir%2Fir.json

Retrieves the list of friends for the current user.

```APIDOC
## POST /get_friend_list

### Description
Retrieves the list of friends for the current user.

### Method
POST

### Endpoint
/get_friend_list

### Parameters
#### Request Body
- **no_cache** (bool) - Optional - 是否强制不使用缓存 (default: false)

### Request Example
```json
{
  "no_cache": true
}
```

### Response
#### Success Response (200)
- **friends** (array[FriendEntity]) - 好友列表

#### Response Example
```json
{
  "friends": [
    {
      "user_id": 987654321,
      "nickname": "FriendOne",
      "remark": "Bestie"
    },
    {
      "user_id": 112233445,
      "nickname": "FriendTwo",
      "remark": "Colleague"
    }
  ]
}
```
```

--------------------------------

### GET /get_group_essence_messages

Source: https://milky.ntqqrev.org/preview_path=milky-ir%2Fir.json

Retrieves a paginated list of essence messages within a group.

```APIDOC
## GET /get_group_essence_messages

### Description
Retrieves a paginated list of essence messages within a group.

### Method
GET

### Endpoint
/get_group_essence_messages

### Parameters
#### Query Parameters
- **group_id** (int64) - Required - The ID of the group.
- **page_index** (int32) - Required - The page index, starting from 0.
- **page_size** (int32) - Required - The number of essence messages per page.

### Response
#### Success Response (200)
(Response fields not detailed in the provided text, but would typically include a list of message objects)

#### Response Example
```json
{
  "messages": [
    {
      "message_id": "msg_abc",
      "content": "This is an essence message.",
      "sender_id": 112233445,
      "timestamp": 1678886400
    }
  ],
  "total_count": 50
}
```
```

--------------------------------

### Get Implementation Info API

Source: https://milky.ntqqrev.org/preview_path=json-schema%2Fschema.json

Retrieves information about the protocol implementation, including its name, version, and supported QQ protocol details.

```APIDOC
## GET /get_impl_info

### Description
Retrieves information about the protocol implementation, including its name, version, and supported QQ protocol details.

### Method
GET

### Endpoint
/get_impl_info

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **impl_name** (string) - The name of the protocol implementation.
- **impl_version** (string) - The version of the protocol implementation.
- **qq_protocol_version** (string) - The QQ protocol version used by the implementation.
- **qq_protocol_type** (string) - The platform of the QQ protocol (e.g., "windows", "android_phone").
- **milky_version** (string) - The version of the Milky protocol implemented (currently "1.1").

#### Response Example
```json
{
  "impl_name": "MilkyNTQQ",
  "impl_version": "1.0.0",
  "qq_protocol_version": "8.9.78",
  "qq_protocol_type": "android_phone",
  "milky_version": "1.1"
}
```
```

--------------------------------

### Get Message API

Source: https://milky.ntqqrev.org/preview_path=kotlin%2Fkotlinx-serialization.txt

Retrieves a specific message.

```APIDOC
## GET /get_message

### Description
Retrieves a specific message.

### Method
GET

### Endpoint
/get_message

### Parameters
#### Query Parameters
- **message_id** (string) - Required - The ID of the message to retrieve.

#### Request Body
None

### Response
#### Success Response (200)
- **data** (object) - The message object.

#### Response Example
```json
{
  "data": {
    "message_id": "msg123",
    "content": "Hello!",
    "sender_id": 123456789,
    "timestamp": 1678886400
  }
}
```
```

--------------------------------

### Define Get Implementation Info API (Kotlin)

Source: https://milky.ntqqrev.org/preview_path=kotlin%2Fkotlinx-serialization.txt

Defines the input and output for retrieving information about the protocol implementation. The input is an empty struct, and the output provides details about the implementation name, versions, and platform.

```kotlin
typealias GetImplInfoInput = ApiEmptyStruct

@Serializable
class GetImplInfoOutput(
    /** 协议端名称 */
    @SerialName("impl_name") val implName: String,
    /** 协议端版本 */
    @SerialName("impl_version") val implVersion: String,
    /** 协议端使用的 QQ 协议版本 */
    @SerialName("qq_protocol_version") val qqProtocolVersion: String,
    /** 协议端使用的 QQ 协议平台 */
    @SerialName("qq_protocol_type") val qqProtocolType: String,
    /** 协议端实现的 Milky 协议版本，目前为 "1.1" */
    @SerialName("milky_version") val milkyVersion: String,
)
```

--------------------------------

### GET /get_forwarded_messages

Source: https://milky.ntqqrev.org/preview_path=milky-ir%2Fir.json

Retrieves the content of merged forwarded messages using the forward ID.

```APIDOC
## GET /get_forwarded_messages

### Description
Retrieves the content of merged forwarded messages using the forward ID.

### Method
GET

### Endpoint
/get_forwarded_messages

### Parameters
#### Query Parameters
- **forward_id** (string) - Required - The ID of the forwarded message

### Response
#### Success Response (200)
- **messages** (array of IncomingForwardedMessage) - The content of the forwarded messages

#### Response Example
```json
{
  "messages": [
    {
      "content": "Forwarded message 1"
    },
    {
      "content": "Forwarded message 2"
    }
  ]
}
```
```

--------------------------------

### Milky 1.1 Kotlinx Serialization Setup

Source: https://milky.ntqqrev.org/preview_path=kotlin%2Fkotlinx-serialization.txt

Sets up the Kotlinx Serialization environment for Milky 1.1, including version constants, a literal default annotation, and a configured Json instance for handling unknown keys and explicit nulls.

```kotlin
// Generated from Milky 1.1 (1.1.0)
@file:OptIn(ExperimentalSerializationApi::class)

package org.ntqqrev.milky

import kotlinx.serialization.Serializable
import kotlinx.serialization.*
import kotlinx.serialization.json.*

const val milkyVersion = "1.1"
const val milkyPackageVersion = "1.1.0"

@Target(AnnotationTarget.PROPERTY)
annotation class LiteralDefault(val value: String)

val milkyJsonModule = Json {
    ignoreUnknownKeys = true
    explicitNulls = false
}
```

--------------------------------

### System API: Get Group List

Source: https://milky.ntqqrev.org/api/system

Retrieves the list of groups the current QQ account is a member of. Supports cache control.

```APIDOC
## GET /get_group_list

### Description
Retrieves the list of groups the current QQ account is a member of. Supports cache control.

### Method
GET

### Endpoint
/get_group_list

### Parameters
#### Path Parameters
None

#### Query Parameters
- **no_cache** (boolean) - Optional - Whether to force not using the cache. Defaults to `false`.

#### Request Body
None

### Request Example
```json
{
  "no_cache": true
}
```

### Response
#### Success Response (200)
- **groups** (GroupEntity[]) - An array of group entities.

#### Response Example
```json
{
  "groups": [
    {
      "group_id": 100000001,
      "group_name": "Awesome Group"
    },
    {
      "group_id": 100000002,
      "group_name": "Another Group"
    }
  ]
}
```
```

--------------------------------

### Event Push: WebHook Request Example (HTTP)

Source: https://milky.ntqqrev.org/guide/communication

Demonstrates a WebHook POST request to a specified URL, containing event data in JSON format. The Authorization header can be used for security.

```http
POST http://example.com/webhook
Content-Type: application/json
 
{
  "time": 1234567890,
  "self_id": 123456789,
  "event_type": "message_receive",
  "data": {
    "message_scene": "friend",
    "peer_id": 123456789,
    "message_seq": 23333,
    "sender_id": 123456789,
    "time": 1234567890,
    "segments": [
      {
        "type": "text",
        "data": {
          "text": "Hello, world!"
        }
      }
    ]
  }
}
```

--------------------------------

### System API: Set Bio

Source: https://milky.ntqqrev.org/api/system

Sets a new personal signature (bio) for the QQ account.

```APIDOC
## POST /set_bio

### Description
Sets a new personal signature (bio) for the QQ account.

### Method
POST

### Endpoint
/set_bio

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **new_bio** (string) - Required - The new personal signature for the QQ account.

### Request Example
```json
{
  "new_bio": "Living life to the fullest!"
}
```

### Response
#### Success Response (200)
- This API has no output parameters.

#### Response Example
```json
{}
```
```

--------------------------------

### Get Forwarded Messages API

Source: https://milky.ntqqrev.org/api/message

Retrieves the content of a forwarded message using its forward ID.

```APIDOC
## GET /get_forwarded_messages

### Description
Retrieves the content of a forwarded message using its forward ID.

### Method
GET

### Endpoint
/get_forwarded_messages

### Parameters
#### Path Parameters
None

#### Query Parameters
- **forward_id** (string) - Required - The ID of the forwarded message.

### Request Example
```
GET /get_forwarded_messages?forward_id=fwd_def456
```

### Response
#### Success Response (200)
- **messages** (IncomingForwardedMessage[]) - An array containing the content of the forwarded messages.

#### Response Example
```json
{
  "messages": [
    {
      "message_id": "msg_126",
      "message_type": "text",
      "content": {"text": "Forwarded message 1"},
      "sender": {"user_id": 111111111},
      "time": 1678886100
    },
    {
      "message_id": "msg_127",
      "message_type": "image",
      "content": {"url": "https://example.com/images/img1.png"},
      "sender": {"user_id": 222222222},
      "time": 1678886000
    }
  ]
}
```
```

--------------------------------

### Event Push: WebSocket Connection Request with Query Token (URL)

Source: https://milky.ntqqrev.org/guide/communication

Example of how to provide an access token via a query parameter for a WebSocket connection, useful when custom headers are not supported.

```url
ws://{IP}:{端口}/event?access_token=123456
```

--------------------------------

### Get Group Info

Source: https://milky.ntqqrev.org/preview_path=openapi%2Fopenapi.json

Retrieves detailed information about a specific group.

```APIDOC
## GET /api/group/info

### Description
Retrieves detailed information about a specific group.

### Method
GET

### Endpoint
/api/group/info

### Parameters
#### Query Parameters
- **group_id** (integer) - Required - The ID of the group to retrieve information for.
- **no_cache** (boolean) - Optional - Whether to force a cache miss.

### Request Example
```json
{
  "group_id": 11111,
  "no_cache": false
}
```

### Response
#### Success Response (200)
- **group** (object) - An object containing the group's information.
  - **group_id** (integer) - The group ID.
  - **group_name** (string) - The group name.
  - **owner_id** (integer) - The ID of the group owner.

#### Response Example
```json
{
  "group": {
    "group_id": 11111,
    "group_name": "Awesome Group",
    "owner_id": 123456789
  }
}
```
```

--------------------------------

### Get Group List

Source: https://milky.ntqqrev.org/preview_path=openapi%2Fopenapi.json

Retrieves a list of groups the user is a part of.

```APIDOC
## GET /api/group/list

### Description
Retrieves a list of groups the user is a part of.

### Method
GET

### Endpoint
/api/group/list

### Parameters
#### Query Parameters
- **no_cache** (boolean) - Optional - Whether to force a cache miss.

### Request Example
```json
{
  "no_cache": false
}
```

### Response
#### Success Response (200)
- **groups** (array) - A list of group objects.

#### Response Example
```json
{
  "groups": [
    {
      "group_id": 11111,
      "group_name": "Awesome Group",
      "owner_id": 123456789
    },
    {
      "group_id": 22222,
      "group_name": "Study Buddies",
      "owner_id": 987654321
    }
  ]
}
```
```

--------------------------------

### Create Group Folder Input and Output Definitions (Kotlin)

Source: https://milky.ntqqrev.org/preview_path=kotlin%2Fkotlinx-serialization.txt

Defines the input for creating a new folder within a group, specifying the group ID and the desired folder name. The output structure is not detailed here but is expected to contain information about the created folder.

```kotlin
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable

@Serializable
class CreateGroupFolderInput(
    /** 群号 */
    @SerialName("group_id") val groupId: Long,
    /** 文件夹名称 */
    @SerialName("folder_name") val folderName: String,
)

@Serializable
class CreateGroupFolderOutput(
```

--------------------------------

### Get Friend Info

Source: https://milky.ntqqrev.org/preview_path=openapi%2Fopenapi.json

Retrieves detailed information about a specific friend.

```APIDOC
## GET /api/friend/info

### Description
Retrieves detailed information about a specific friend.

### Method
GET

### Endpoint
/api/friend/info

### Parameters
#### Query Parameters
- **user_id** (integer) - Required - The ID of the friend to retrieve information for.
- **no_cache** (boolean) - Optional - Whether to force a cache miss.

### Request Example
```json
{
  "user_id": 123456789,
  "no_cache": false
}
```

### Response
#### Success Response (200)
- **friend** (object) - An object containing the friend's information.
  - **user_id** (integer) - The friend's user ID.
  - **user_name** (string) - The friend's username.
  - **remark** (string) - The friend's remark.

#### Response Example
```json
{
  "friend": {
    "user_id": 123456789,
    "user_name": "Friend Name",
    "remark": "Bestie"
  }
}
```
```

--------------------------------

### Event Push: SSE Connection Request with Query Token (HTTP)

Source: https://milky.ntqqrev.org/guide/communication

Alternative method for establishing an SSE connection using a query parameter for the access token, useful in environments that don't support custom headers.

```http
GET /event?access_token=123456
```

--------------------------------

### Get Friend List

Source: https://milky.ntqqrev.org/preview_path=openapi%2Fopenapi.json

Retrieves a list of the user's friends.

```APIDOC
## GET /api/friend/list

### Description
Retrieves a list of the user's friends.

### Method
GET

### Endpoint
/api/friend/list

### Parameters
#### Query Parameters
- **no_cache** (boolean) - Optional - Whether to force a cache miss.

### Request Example
```json
{
  "no_cache": false
}
```

### Response
#### Success Response (200)
- **friends** (array) - A list of friend objects.

#### Response Example
```json
{
  "friends": [
    {
      "user_id": 123456789,
      "user_name": "Friend Name",
      "remark": "Bestie"
    },
    {
      "user_id": 987654321,
      "user_name": "Another Friend",
      "remark": "Colleague"
    }
  ]
}
```
```

--------------------------------

### GET /get_impl_info

Source: https://milky.ntqqrev.org/preview_path=openapi%2Fopenapi.json

Retrieves information about the protocol implementation, including names, versions, and QQ protocol details.

```APIDOC
## GET /get_impl_info

### Description
Retrieves information about the protocol implementation, including names, versions, and QQ protocol details.

### Method
GET

### Endpoint
/get_impl_info

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **impl_name** (string) - Protocol implementation name
- **impl_version** (string) - Protocol implementation version
- **qq_protocol_version** (string) - QQ protocol version used by the implementation
- **qq_protocol_type** (string) - QQ protocol platform (e.g., "windows", "android_phone")
- **milky_version** (string) - Milky protocol version implemented (currently "1.1")

#### Response Example
```json
{
  "impl_name": "NTQQ",
  "impl_version": "9.9.9",
  "qq_protocol_version": "8.9.45",
  "qq_protocol_type": "android_phone",
  "milky_version": "1.1"
}
```
```

--------------------------------

### Get User Profile

Source: https://milky.ntqqrev.org/preview_path=openapi%2Fopenapi.json

Retrieves the profile information for a given user.

```APIDOC
## GET /api/user/profile

### Description
Retrieves the profile information for a given user.

### Method
GET

### Endpoint
/api/user/profile

### Parameters
#### Query Parameters
- **user_id** (integer) - Required - The ID of the user to retrieve the profile for.
- **no_cache** (boolean) - Optional - Whether to force a cache miss.

### Request Example
```json
{
  "user_id": 123456789,
  "no_cache": false
}
```

### Response
#### Success Response (200)
- **remark** (string) - User's remark.
- **bio** (string) - User's bio.
- **level** (integer) - User's level.
- **country** (string) - User's country.
- **city** (string) - User's city.
- **school** (string) - User's school.

#### Response Example
```json
{
  "remark": "My Friend",
  "bio": "Hello there!",
  "level": 10,
  "country": "USA",
  "city": "New York",
  "school": "Example University"
}
```
```

--------------------------------

### Define Get Login Info API (Kotlin)

Source: https://milky.ntqqrev.org/preview_path=kotlin%2Fkotlinx-serialization.txt

Defines the input and output structures for the GetLoginInfo API. The input is an empty struct, while the output contains the logged-in QQ number and nickname.

```kotlin
typealias GetLoginInfoInput = ApiEmptyStruct

@Serializable
class GetLoginInfoOutput(
    /** 登录 QQ 号 */
    @SerialName("uin") val uin: Long,
    /** 登录昵称 */
    @SerialName("nickname") val nickname: String,
)
```

--------------------------------

### Get Group Notifications

Source: https://milky.ntqqrev.org/preview_path=dart%2Fjson_serializable.txt

Retrieves a list of notifications for a group.

```APIDOC
## POST /get_group_notifications

### Description
Retrieves a list of notifications for a group.

### Method
POST

### Endpoint
/get_group_notifications

### Parameters
#### Request Body
- **input** (object) - Required - The input object for getting group notifications.

### Request Example
```json
{
  "input": { ... }
}
```

### Response
#### Success Response (200)
- **output** (object) - The output object containing the list of group notifications.

#### Response Example
```json
{
  "output": { ... }
}
```
```

--------------------------------

### Get Forwarded Messages API

Source: https://milky.ntqqrev.org/preview_path=kotlin%2Fkotlinx-serialization.txt

Retrieves the content of forwarded messages.

```APIDOC
## GET /get_forwarded_messages

### Description
Retrieves the content of forwarded messages.

### Method
GET

### Endpoint
/get_forwarded_messages

### Parameters
#### Query Parameters
- **message_id** (string) - Required - The ID of the forwarded message.

#### Request Body
None

### Response
#### Success Response (200)
- **data** (array) - A list of message objects that were forwarded.

#### Response Example
```json
{
  "data": [
    {
      "message_id": "fwd_msg1",
      "content": "Forwarded message content",
      "sender_id": 123456789,
      "timestamp": 1678886500
    }
  ]
}
```
```

--------------------------------

### GET /get_login_info

Source: https://milky.ntqqrev.org/preview_path=openapi%2Fopenapi.json

Retrieves the login information for the current QQ account, including the user's UIN and nickname.

```APIDOC
## GET /get_login_info

### Description
Retrieves the login information for the current QQ account, including the user's UIN and nickname.

### Method
GET

### Endpoint
/get_login_info

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **uin** (integer) - Login QQ number
- **nickname** (string) - Login nickname

#### Response Example
```json
{
  "uin": 1234567890,
  "nickname": "ExampleUser"
}
```
```

--------------------------------

### API Response: Failed Example (JSON)

Source: https://milky.ntqqrev.org/guide/communication

Illustrates a failed API response from the Milky protocol. It includes a status, an error retcode, and a message explaining the failure reason.

```json
{
  "status": "failed",
  "retcode": -403,
  "message": "未处于登录状态"
}
```

--------------------------------

### Get Resource Temporary URL API

Source: https://milky.ntqqrev.org/api/message

Generates a temporary URL for accessing a resource using its ID.

```APIDOC
## GET /get_resource_temp_url

### Description
Generates a temporary URL for accessing a resource using its ID.

### Method
GET

### Endpoint
/get_resource_temp_url

### Parameters
#### Path Parameters
None

#### Query Parameters
- **resource_id** (string) - Required - The ID of the resource.

### Request Example
```
GET /get_resource_temp_url?resource_id=res_abc123
```

### Response
#### Success Response (200)
- **url** (string) - The temporary URL for the resource.

#### Response Example
```json
{
  "url": "https://example.com/temp/res_abc123?token=xyz789"
}
```
```

--------------------------------

### Get History Messages API

Source: https://milky.ntqqrev.org/api/message

Retrieves a list of historical messages within a specified scene and peer.

```APIDOC
## GET /get_history_messages

### Description
Retrieves a list of historical messages within a specified scene and peer.

### Method
GET

### Endpoint
/get_history_messages

### Parameters
#### Path Parameters
None

#### Query Parameters
- **message_scene** (enum) - Required - The scene of the messages (e.g., `friend`, `group`, `temp`).
- **peer_id** (int64) - Required - The QQ number of the friend or the group number.
- **start_message_seq** (int64?) - Optional - The starting message sequence number to query from (older messages first). If not provided, queries from the latest messages.
- **limit** (int32) - Optional - The maximum number of messages to retrieve (default: 20, max: 30).

### Request Example
```
GET /get_history_messages?message_scene=group&peer_id=987654321&limit=10
```

### Response
#### Success Response (200)
- **messages** (IncomingMessage[]) - An array of retrieved messages, sorted by `message_seq` in ascending order. Some messages might be missing (e.g., recalled messages).
- **next_message_seq** (int64?) - Optional - The message sequence number for the next page of results.

#### Response Example
```json
{
  "messages": [
    {
      "message_id": "msg_124",
      "message_type": "text",
      "content": {"text": "Hello again!"},
      "sender": {"user_id": 987654321},
      "time": 1678886300
    },
    {
      "message_id": "msg_125",
      "message_type": "text",
      "content": {"text": "Another message."},
      "sender": {"user_id": 987654321},
      "time": 1678886200
    }
  ],
  "next_message_seq": 1234567890123450
}
```
```

--------------------------------

### Get Message API

Source: https://milky.ntqqrev.org/api/message

Retrieves a specific message based on its scene, peer ID, and sequence number.

```APIDOC
## GET /get_message

### Description
Retrieves a specific message based on its scene, peer ID, and sequence number.

### Method
GET

### Endpoint
/get_message

### Parameters
#### Path Parameters
None

#### Query Parameters
- **message_scene** (enum) - Required - The scene of the message (e.g., `friend`, `group`, `temp`).
- **peer_id** (int64) - Required - The QQ number of the friend or the group number.
- **message_seq** (int64) - Required - The sequence number of the message.

### Request Example
```
GET /get_message?message_scene=friend&peer_id=123456789&message_seq=1234567890123456
```

### Response
#### Success Response (200)
- **message** (IncomingMessage) - The content of the retrieved message.

#### Response Example
```json
{
  "message": {
    "message_id": "msg_123",
    "message_type": "text",
    "content": {"text": "Hello!"},
    "sender": {"user_id": 123456789},
    "time": 1678886400
  }
}
```
```

--------------------------------

### Get Group Files Input and Output Definitions (Kotlin)

Source: https://milky.ntqqrev.org/preview_path=kotlin%2Fkotlinx-serialization.txt

Defines the input for listing files and folders within a group, specifying the group ID and parent folder ID. The output includes lists of files and folders.

```kotlin
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable

@Serializable
class GetGroupFilesInput(
    /** 群号 */
    @SerialName("group_id") val groupId: Long,
    /** 父文件夹 ID */
    @SerialName("parent_folder_id") @LiteralDefault("\"/\"") val parentFolderId: String = "/",
)

@Serializable
class GetGroupFilesOutput(
    /** 文件列表 */
    @SerialName("files") val files: List<GroupFileEntity>,
    /** 文件夹列表 */
    @SerialName("folders") val folders: List<GroupFolderEntity>,
)
```

--------------------------------

### Set Nickname API

Source: https://milky.ntqqrev.org/preview_path=kotlin%2Fkotlinx-serialization.txt

Sets the QQ account nickname.

```APIDOC
## POST /set_nickname

### Description
Sets the QQ account nickname.

### Method
POST

### Endpoint
/set_nickname

### Parameters
#### Query Parameters
None

#### Request Body
- **nickname** (string) - Required - The new nickname for the QQ account.

### Response
#### Success Response (200)
- **data** (object) - Empty object indicating success.

#### Response Example
```json
{
  "data": {}
}
```
```

--------------------------------

### Get Group Files API

Source: https://milky.ntqqrev.org/api/file

Retrieves a list of files and folders within a specified group folder.

```APIDOC
## GET /get_group_files

### Description
Retrieves a list of files and folders within a specified folder in a group chat.

### Method
GET

### Endpoint
/get_group_files

### Parameters
#### Query Parameters
- **group_id** (int64) - Required - The group number.
- **parent_folder_id** (string) - Optional - The ID of the parent folder. Defaults to `/`.

### Response
#### Success Response (200)
- **files** (GroupFileEntity[]) - A list of file entities.
- **folders** (GroupFolderEntity[]) - A list of folder entities.

#### Response Example
```json
{
  "files": [
    {
      "file_id": "file1_id",
      "file_name": "document.pdf"
    }
  ],
  "folders": [
    {
      "folder_id": "folder1_id",
      "folder_name": "Images"
    }
  ]
}
```
```

--------------------------------

### GET /api/group/file/download_url

Source: https://milky.ntqqrev.org/preview_path=json-schema%2Fschema.json

Retrieves the download URL for a specific group file.

```APIDOC
## GET /api/group/file/download_url

### Description
Retrieves the download URL for a specific group file based on its group ID and file ID.

### Method
GET

### Endpoint
/api/group/file/download_url

### Parameters
#### Query Parameters
- **group_id** (integer) - Required - The group number.
- **file_id** (string) - Required - The ID of the file.

### Request Example
```json
{
  "group_id": 12345,
  "file_id": "file123abc"
}
```

### Response
#### Success Response (200)
- **download_url** (string) - The URL to download the file.
```

--------------------------------

### Define Get User Profile API (Kotlin)

Source: https://milky.ntqqrev.org/preview_path=kotlin%2Fkotlinx-serialization.txt

Defines the input and output for fetching a user's profile. The input requires a user ID, and the output includes detailed profile information such as nickname, QID, age, sex, bio, level, and location.

```kotlin
@Serializable
class GetUserProfileInput(
    /** 用户 QQ 号 */
    @SerialName("user_id") val userId: Long,
)

@Serializable
class GetUserProfileOutput(
    /** 昵称 */
    @SerialName("nickname") val nickname: String,
    /** QID */
    @SerialName("qid") val qid: String,
    /** 年龄 */
    @SerialName("age") val age: Int,
    /** 性别 */
    @SerialName("sex") val sex: String,
    /** 备注 */
    @SerialName("remark") val remark: String,
    /** 个性签名 */
    @SerialName("bio") val bio: String,
    /** QQ 等级 */
    @SerialName("level") val level: Int,
    /** 国家或地区 */
    @SerialName("country") val country: String,
    /** 城市 */
    @SerialName("city") val city: String,
    /** 学校 */
    @SerialName("school") val school: String,
)
```

--------------------------------

### Create Group Folder

Source: https://milky.ntqqrev.org/preview_path=kotlin%2Fkotlinx-serialization.txt

Creates a new folder for files within a group. The `CreateGroupFolder` endpoint handles this, requiring `CreateGroupFolderInput` and yielding `CreateGroupFolderOutput`.

```Kotlin
/** 创建群文件夹 */
    object CreateGroupFolder : ApiEndpoint<CreateGroupFolderInput, CreateGroupFolderOutput>("/create_group_folder")
```