# API

이곳에서는 API 요청의 기본적인 정보를 안내합니다.

## Base URL

모든 API의 기본 URL입니다.

```
https://koreanbots.dev/api
```

모든 엔드포인트의 요청은 이곳으로 보내게 됩니다.

요청을 보낼 때 반드시 API 버전을 포함하여 보내야 합니다.

## 버전

API 요청을 보낼 때는 다음과 같이 사용합니다.
`https://koreanbots.dev/api/v{version}`

<message type="info">
  `v2` 버전의 API를 사용해주세요.
</message>

| 버전     | 상태   |
|---------|-------|
|   2    |사용 가능|
|   1    |지원 종료|
|   0    |사용 불가|

<h2 id="ratelimit">레이트리밋</h2>

<Message type='error'>레이트리밋(RateLimit)은 로그인 토큰 기준이 아닌, IP 기준으로 적용됩니다. <br/> 레이트리밋은 클라이언트와 동일 IP로 접속할 경우 공유하게 됩니다.</Message>

효율적인 리소스 관리를 위한 일정시간의 요청 제한 시간입니다.

만약 제한된 요청 횟수보다 더 많이 요청할 경우 `429`의 **STATUSCODE**(상태코드)를 반환합니다.

### 엔드포인트별 레이트리밋

반환 상태코드가 `200`(SUCCESS)가 아닌 `400~500` 사이의 상태코드일 경우에도 레이트리밋은 카운트됩니다.

| ENDPOINT | RATELIMIT |
| -------- | --------- |
| /* (Global)| 180회/분  |

특정 엔드포인트들은 별도의 레이트리밋이 있습니다. [레이트리밋 헤더](#ratelimit-headers)를 통해 정보를 확인할 수 있습니다.

<h2 id="ratelimit-headers">레이트리밋 헤더</h2>

| 헤더명 | 설명 |
|-------|------|
| x-ratelimit-limit | 해당 엔드포인트에서 허용되는 요청 횟수입니다. |
| x-ratelimit-remaining | 남은 요청 가능 횟수입니다. |
| x-ratelimit-reset | 횟수 카운트가 리셋되는 시간입니다. |
| x-ratelimit-global | 레이트리밋 헤더가 라우트별이 아닌 글로벌 레이트리밋임을 의미하는지를 나타냅니다. |


# 언어별 SDK

<message type="info">API 링크로 요청하는 대신, SDK를 사용하시면 더 간편하게 사용하실 수 있습니다.</message>

## Javascript

[NPM](https://npmjs.org/koreanbots) [Github](https://github.com/koreanbots/js-sdk)

## Python

[PYPI](https://pypi.org/project/koreanbots/) [Github](https://github.com/koreanbots/py-sdk)

## 비공식 라이브러리

<message type="info">
  한국 디스코드봇 리스트에서 제작한 것이 아닌 커뮤니티 유저분들이 제작해주신 SDK입니다.<br/>
  본인이 제작한 라이브러리가 있으시다면 이곳에 추가하실 수 있습니다. 문의해주세요!
</message>

## Kotlin (Java)

[Koreanbots-Kotlin-SDK](https://github.com/JellyBrick/Koreanbots-Kotlin-SDK)

## Rust

[Koreanbots.rs](https://github.com/AkiaCode/Koreanbots.rs)

## Go

[gokoreanbots](https://github.com/simsimler/gokoreanbots)

## C# ##

[SharpKoreanBots]( https://github.com/csnewcs/SharpKoreanBots)


시작하기

# 시작하기

안녕하세요. `Koreanbots` 공식 API 문서에 오신 것을 환영합니다.

이 곳에서 **API**에 관한 모든 것을 알아보세요.

---

행운을 빕니다 XD

## 버그 제보

이슈는 [이곳](https://github.com/koreanbots/koreanbots/issues)에서 트래킹 됩니다.

## 약관

API를 사용하실 때는 반드시 [약관](./약관)을 따라야합니다.

## 도움받기

질문이 있으신가요? [공식 디스코드](https://discord.gg/JEh53MQ)에서 도와드리죠!


약관

# 한국 디스코드 리스트 개발자 약관

해당 약관은 한국 디스코드 리스트(이하 "당사")의 API 및 공식 SDK를 사용, 활용 등에 관한 내용입니다.

이 외에도 당사의 서비스를 크롤링 하거나 기타 자동화된 방법으로 수집, 사용하는 경우에 관하여도 규정합니다.

해당 규정을 위반할 경우 서비스 이용 제한 조치 및 봇 삭제 등의 조치가 취해질 수 있습니다.

## 투표 보상

### 일반적인 투표 보상

봇/서버에 투표를 한 대가로 다음과 같은 보상을 지급할 수 있습니다.

- 실물 화폐가 아닌 봇/서버 속 가상 화폐
- 쿨타임 감소와 같은 혜택
- 디스코드 서버에서의 역할
- **일부** 명령어 사용 권한 (2~3개의 명령어)
- 등...

위 사항은 권장하는 예시들이며 다른 창의적인 아이디어가 있으시다면 해당 방법을 채택해도 됩니다.

하지만 아래 항목들은 금지됩니다.

### 금지사항

#### 타 봇/서버 보상

해당 봇/서버에 대한 투표 보상으로 다른 봇/서버와 관련된 보상이 지급되어서는 안됩니다.

<Message type="info">
  예를 들어, A봇에 대해 투표를 했는데 B봇의 화폐를 지급해서는 안됩니다.
</Message>

#### 처벌

봇/서버에 투표하지 않았다는 이유로 유저를 처벌해서는 안됩니다.

#### 직접적인 금전적 보상

투표의 보상으로 직접적인 금전적 보상을 지급해서는 안됩니다. (실제 화폐(비트코인과 같은 가상화폐 포함), 문화상품권 등)

#### 투표 강제

유저에게 봇/서버의 투표를 강제해서는 안됩니다. (예: 투표를 해야만 **전체** 명령어를 사용할 수 있는 등)

#### 보상의 이전 또는 양도

한 유저가 받은 투표 보상은 다른 유저에게 직접적으로 이전 또는 양도되어서는 안됩니다.

<Message type="info">
  예를 들어, A가 받은 화폐 보상이 송금 기능 등을 이용해 B로 이전될 수 없습니다.
</Message>

## 어뷰징

### 자동화

매크로나 기타 자동화 도구 혹은 소프트웨어 등을 사용/제작하여 봇/서버 투표를 자동화 하는 행위는 금지됩니다.

### 부계정

많은 부계정을 생성하여 하나 이상의 봇/서버에 지속적으로 투표하는 행위는 금지됩니다.



웹후크

# 웹후크

<Message type="info">디스코드 웹후크를 사용하시는 경우 아래 모든 내용은 유효하지 않습니다.</Message>

- 문서의 다른 정보와 달리 웹후크의 경우 클라이언트가 서버로 요청을 보내는 것이 아닌 서버가 클라이언트로 요청을 보내는 것이므로 참고하실 때 유의해주시기 바랍니다.

## 웹후크 주소 검증 절차

- 한디리는 등록하려는 웹후크 주소가 유효한지 확인하기 위해 웹후크 주소에 `GET` 요청을 보냅니다.  
  해당 요청에는 검증된 웹후크를 수신하는 데 필요한 시크릿 키가 포함됩니다.
- 요청을 받은 서버에서 후술하는 바와 같이 응답해야 웹후크가 등록됩니다.

### `GET`

#### Query String

| FIELD    | TYPE   | DESCRIPTION |
| -------- | ------ | ----------- |
| secret\* | string | 시크릿 키   |

- `secret`에 제공되는 문자열은 수신한 웹후크가 한디리에서 보낸 유효한 웹후크인지 확인할 때 사용할 수 있습니다.

#### 응답

```tsx
{
  secret: SECRET
}
```

#### 요청 예시

`GET` /?secret=66682ec7-cccd-4640-8df3-601e3e43060f

#### 응답 예시

```json
{
  "secret": "66682ec7-cccd-4640-8df3-601e3e43060f"
}
```

<Message type=”warning”>

응답에 실패한 경우 `웹후크 주소를 검증할 수 없습니다.` 라고 표시되며, 봇 또는 서버 정보 수정이 이루어지지 않습니다.

</Message>

## 웹후크 정보

### 구조

| FIELD       | TYPE   | DESCRIPTION                 |
| ----------- | ------ | --------------------------- |
| type        | string | 웹후크 이벤트의 타입        |
| data        | object | 웹후크 데이터               |
| timestamp\* | number | 웹후크 이벤트가 발생한 시각 |

- `timestamp`는 UNIX Epoch로부터 경과한 밀리초 시간입니다.

## 웹후크 이벤트 타입(type)

| VALUE  | DESCRIPTION |
| ------ | ----------- |
| bot    | 봇          |
| server | 서버        |

## 웹후크 데이터

### 구조

| FIELD    | TYPE     | DESCRIPTION                                 |
| -------- | -------- | ------------------------------------------- |
| type     | integer  | 웹후크 데이터의 타입                        |
| botId?   | string   | 봇의 웹후크인 경우 봇 ID                    |
| guildId? | string   | 서버의 웹후크인 경우 서버 ID                |
| before   | ?integer | 데이터의 변동 전의 값                       |
| after    | integer  | 데이터의 변동 후의 값                       |
| userId\* | string   | 하트 수 변동일 경우 하트를 추가한 유저의 ID |

- `userId`는 웹후크의 type이 `0`인 경우에만 제공됩니다.

## 웹후크 데이터 구분(type)

| VALUE | DESCRIPTION  |
| ----- | ------------ |
| 0     | 하트 수 변동 |
| 1     | 서버 수 변동 |

## 웹후크 이벤트

- 한디리에서 보내는 웹후크는 `POST` 요청으로 보내집니다.

### 웹후크에 대한 응답

- 보낸 웹후크에 대한 응답은 다음과 같이 이루어져야 하며, 한디리가 보낸 요청에 응답하지 않거나 올바르지 않게 응답한 경우 웹후크가 **비활성화**됩니다.
- 한디리가 보낸 요청에 `10`초 안으로 응답하지 않은 경우 웹후크는 응답하지 않은 것으로 간주됩니다.

| 구분      | 내용      |
| --------- | --------- |
| 응답 코드 | `2xx`     |
| 응답 본문 | 빈 문자열 |

- `4xx` 형식의 응답 코드를 반환한 경우 웹후크는 **즉시** 비활성화됩니다.
- 응답 본문이 비어있지 않은 경우 웹후크는 **즉시** 비활성화됩니다.
- 이외의 다른 비정상 반환이 발생할 경우 한디리에서는 웹후크 재전송을 시도합니다. 웹후크 재전송에 관한 내용은 [아래](#실패한-웹후크-재전송)를 참조해주세요.

### 웹후크 내용 검증하기

- 웹후크가 한디리에서 보낸 것인지 검증하려면 최초에 한디리가 보낸 `GET` 요청에 포함되었던 시크릿 키를 사용해야 합니다.
- 해당 시크릿 키는 매 요청마다 `secret` 헤더에 포함되어 전송됩니다.

#### 하트 추가 이벤트 예시

```json
{
  "type": "server",
  "data": {
    "type": 0,
    "guildId": "653083797763522580",
    "before": 0,
    "after": 1,
    "userId": "288302173912170497"
  },
  "timestamp": 1682252410000
}
```

#### 서버 수 변동 이벤트 예시

```json
{
  "type": "bot",
  "data": {
    "type": 1,
    "botId": "872349051620831292",
    "before": 1000,
    "after": 1001
  },
  "timestamp": 1682252410000
}
```

## 실패한 웹후크 재전송

- 한디리는 전송에 실패한 웹후크에 대해 총 10번의 재전송을 시도합니다.  
  처음 재전송은 최초 실패시부터 `4`초 후에 이루어지며, 재전송이 실패할 때마다 재전송 간격이 `2`배씩 증가하며, 최대 `4096`초까지 증가합니다.
- 10번의 재전송이 모두 실패한 경우 해당 웹후크는 다시 받을 수 없습니다.
- 처음 10번의 재전송이 모두 실패한 이후로 `24`시간 이상 웹후크 전송이 지속적으로 실패한 경우 경우 웹후크가 **비활성화**됩니다.


# 봇

<h2 id="bot">
  봇 정보
</h2>

### 구조

| FIELD | TYPE | DESCRIPTION |
|-------|------|-------------|
| id | string | 봇의 ID |
| name | string | 봇의 디스코드 유저네임 |
| tag | string | 봇의 디스코드 태그 |
| avatar | ?string | 봇의 아바타 해시 |
| owners | [User](./유저#user)[]  | 봇의 소유자 (단, 소유한 봇은 아이디만 표시됩니다) |
| flags | integer | 봇의 [플래그](#flags) |
| lib | string | 봇의 라이브러리 |
| prefix | string | 봇의 접두사 |
| votes | integer | 봇의 하트 수 |
| servers | ?integer | 봇의 서버 수 |
| shards | ?integer | 봇의 샤드 수 |
| intro | string | 봇의 짧은 설명 |
| desc | string | 봇의 긴 설명 |
| web | ?string | 봇의 웹사이트 주소 |
| git | ?string | 봇의 깃 주소 |
| url | ?string | 봇의 커스텀 초대링크 |
| discord | ?string | 봇의 디스코드 초대코드 |
| category | [Category](#category)[] | 봇의 카테고리 |
| vanity | ?string | 봇의 VANITY URL |
| bg | ?string | 봇의 배경 이미지 주소 |
| banner | ?string | 봇의 배너 이미지 주소 |
| status | ?[Status](#status) | 봇의 유저 상태 |
| state | [State](#state) | 한국 디스코드봇 리스트에서의 봇의 상태 |

<h2 id="category">
 봇 카테고리 (Category)
</h2>

- 관리
- 뮤직
- 전적
- 게임
- 도박
- 로깅
- 빗금 명령어
- 웹 대시보드
- 밈
- 레벨링
- 유틸리티
- 대화
- NSFW
- 검색
- 학교
- 코로나19
- 번역
- 오버워치
- 리그 오브 레전드
- 배틀그라운드
- 마인크래프트

<h2 id="status">
  봇 유저 상태 (Status)
</h2>

- online
- idle
- dnd
- streaming
- offline

<h2 id="state">
  봇의 상태 (State)
</h2>

- `ok` 정상
- `reported` 일시 정지
- `blocked` 강제 삭제
- `private` 특수 목적 봇
- `archived` 잠금 처리 (지원 종료)

<h2 id="flags">
  봇 플래그(flags)
</h2>

| VALUE | DESCRIPTION |
|-------|-------------|
| 0 << 0 | 없음 |
| 1 << 0 | 공식 봇 |
| 1 << 2 | 한국 디스코드봇 리스트 인증된 봇 |
| 1 << 3 | 파트너 |
| 1 << 4 | 디스코드 인증된 봇 |
| 1 << 5 | 프리미엄 |
| 1 << 6 | 제1회 한국 디스코드봇 리스트 해커톤 우승자 봇 |

## 봇 정보 가져오기

### `GET` /v2/bots/{bot.id}

[봇 정보](#bot)를 반환합니다.

#### 응답 예시

```json
{
  "code": 200,
  "data": {
    "id": "653534001742741552",
    "flags": 4,
    "owners": [
      {
        "id": "285185716240252929",
        "flags": 0,
        "github": "wonderlandpark",
        "tag": "9999",
        "username": "wonderlandpark",
        "bots": [
          "387548561816027138",
          "530171799980212244",
          "653534001742741552",
          "707156018261524510",
          "707972925181001868",
          "762980393829269507",
          "784618064167698472"
        ]
      }
    ],
    "lib": "discord.js",
    "prefix": "!",
    "votes": 39,
    "servers": 1,
    "intro": "디코봇 리스트 커뮤니티를 관리하기 위한 봇입니다. 공개봇이 아니며, 개인서버에서 사용하실 수 없어요!",
    "desc": "# IU BOT\n![Votes](https://api.koreanbots.dev/widget/bots/votes/653534001742741552.svg)\n## 해당봇은 특수목적용봇입니다.\n\n따로 서버로 초대하거나 사용하실 수 없습니다.\n\n## 목적\n\nKOREANBOTS 사이트의 봇 신청 처리 및 데이터 수정 등을 담당합니다.\n\n## 기능\n\n- approve\n- deny\n- edit\n- todo\n- ...",
    "web": "https://koreanbots.dev",
    "git": "https://github.com/koreanbots",
    "url": "",
    "category": [
      "관리",
      "로깅"
    ],
    "status": "online",
    "discord": "JEh53MQ",
    "state": "private",
    "vanity": "iu",
    "bg": "https://i.imgur.com/mFegdF1.jpg",
    "banner": "https://i.imgur.com/jcn4zaX.jpeg",
    "tag": "2833",
    "avatar": "3c986f863d0c45a329297425c4cbba4e",
    "name": "IU"
  },
  "version": 2
}
```
## 봇 검색하기

### `GET` /v2/search/bots

#### Query String

| FIELD | TYPE | DESCRIPTION |
|-------|------|-------------|
| query | string | 검색어 |
| page | integer | 페이지 번호 (기본값: 1) |

#### 요청 예시
`GET` /v2/search/bots?query=IU&page=1

#### 응답예시
```json
{
  "code": 200,
  "data": {
    "type": "SEARCH",
    "data": [
      {
        "id": "653534001742741552",
        "flags": 21,
        "owners": [
          {
            "id": "285185716240252929",
            "flags": 1,
            "github": "wonderlandpark",
            "tag": "9999",
            "username": "wonderlandpark",
            "bots": [
              "387548561816027138",
              "530171799980212244",
              "653534001742741552",
              "707156018261524510",
              "762980393829269507",
              "784618064167698472",
              "788048121548374076"
            ]
          }
        ],
        "lib": "discord.js",
        "prefix": "!",
        "votes": 38,
        "servers": 1,
        "intro": "디코봇 리스트 커뮤니티를 관리하기 위한 봇입니다. 공개봇이 아니며, 개인서버에서 사용하실 수 없어요!",
        "desc": "# IU BOT\n![Votes](https://api.koreanbots.dev/widget/bots/votes/653534001742741552.svg)\n## 해당봇은 특수목적용봇입니다.\n\n따로 서버로 초대하거나 사용하실 수 없습니다.\n\n## 목적\n\nKOREANBOTS 사이트의 봇 신청 처리 및 데이터 수정 등을 담당합니다.\n\n## 기능\n\n- approve\n- deny\n- edit\n- todo\n- ...",
        "web": "https://koreanbots.dev",
        "git": "https://github.com/koreanbots",
        "url": null,
        "category": [
          "관리",
          "로깅"
        ],
        "status": "online",
        "discord": "JEh53MQ",
        "state": "private",
        "vanity": "iu",
        "bg": "https://i.imgur.com/mFegdF1.jpg",
        "banner": "https://i.imgur.com/jcn4zaX.jpeg",
        "tag": "2833",
        "avatar": "3c986f863d0c45a329297425c4cbba4e",
        "name": "IU"
      }
    ],
    "currentPage": 1,
    "totalPage": 1
  },
  "version": 2
}
```

## 하트 랭킹 리스트 가져오기

### `GET` /v2/list/bots/votes

#### Query String

| FIELD | TYPE | DESCRIPTION |
|-------|------|-------------|
| page | integer | 페이지 번호 (기본값: 1) |

## 새로운 봇 리스트 가져오기

### `GET` /v2/list/bots/new

## 유저 봇 투표 여부 확인

### `GET` /v2/bots/{bot.id}/vote

#### Request Header

| FIELD | TYPE |DESCRIPTION |
|-------|------|-------------|
| Authorization | string | 봇의 토큰 |

#### Query String

| FIELD | TYPE | DESCRIPTION |
|-------|------|-------------|
| userID | string | 확인할 유저 아이디 |

#### 반환값
- `voted` 12시간이내 투표 여부
- `lastVote` 가장 최근 투표 시간 (timestamp)

#### 요청 예시

`GET` /v2/bots/653534001742741552/vote?userID=285185716240252929

##### Headers

```
Authorization: SUPER_SECRET_KOREANBOTS_TOKEN
Content-Type: application/json
```

#### 응답 예시

```json
{
  "code": 200,
  "data": {
    "voted": true,
    "lastVote": 1620183276602
  },
  "version": 2
}
```


## 봇 정보 업데이트

### `POST` /v2/bots/{bot.id}/stats

<Message type="error">
  해당 엔드포인트는 추가적인 레이트리밋이 적용됩니다. 따라서 <strong>3분에 3개의 요청</strong>을 보내실 수 있습니다
</Message>

#### Request Header

| FIELD | TYPE |DESCRIPTION |
|-------|------|-------------|
| Authorization | string | 봇의 토큰 |

#### Request Body

| FIELD | TYPE | DESCRIPTION |
|-------|------|-------------|
| servers | integer | 업데이트할 봇의 서버 수 |
| shards | integer | 업데이트할 봇의 샤드 수 |

#### 요청 예시

`POST` /v2/bots/653534001742741552/stats

##### Headers

```
Authorization: SUPER_SECRET_KOREANBOTS_TOKEN
Content-Type: application/json
```

##### Body

```json
{
  "servers": 2,
  "shards": 1,
}
```

#### 응답 예시

```json
{
  "code": 200,
  "version": 2,
  "message": "성공적으로 업데이트 했습니다."
}
```


서버

# 서버

<h2 id="server">
  서버 정보
</h2>

### 구조

<Message type="warning">
  공식적이지 않은 Private Field는 기록하지 않습니다. (bots 등)
</Message>

| FIELD    | TYPE                    | DESCRIPTION                            |
| -------- | ----------------------- | -------------------------------------- |
| id       | string                  | 서버의 ID                              |
| name     | string                  | 서버의 디스코드 유저네임               |
| icon     | ?string                 | 서버의 아바타 해시                     |
| owner    | [User](./유저#user)     | 서버의 소유자                          |
| flags    | integer                 | 서버의 [플래그](#flags)                |
| votes    | integer                 | 서버의 하트 수                         |
| members    | integer                 | 서버의 유저 수                         |
| boostTier    | integer                 | 서버의 부스트 티어 (0~3)                         |
| intro    | string                  | 서버의 짧은 설명                       |
| desc | string | 서버의 긴 설명 |
| category | [Category](#category)[] | 서버의 카테고리                        |
| invite   | string                  | 서버의 초대코드                        |
| emojis   | [Emoji](#emoji)[]       | 서버의 이모지                          |
| vanity   | ?string                 | 서버의 VANITY URL                      |
| bg       | ?string                 | 서버의 배경 이미지 주소                |
| banner   | ?string                 | 서버의 배너 이미지 주소                |
| state    | [State](#state)         | 한국 디스코드 리스트에서의 서버의 상태 |

<h2 id="emoji">
  서버 이모지 (Emoji)
</h2>

### 구조

| FIELD | TYPE   | DESCRIPTION |
| ----- | ------ | ----------- |
| id    | string | 이모지 ID   |
| name  | string | 이모지 이름 |
| url   | string | 이모지 URL  |

<h2 id="category">
 서버 카테고리 (Category)
</h2>

- 커뮤니티
- IT & 과학
- 봇
- 친목
- 음악
- 교육
- 연애
- 게임
- 오버워치
- 리그 오브 레전드
- 배틀그라운드
- 마인크래프트

<h2 id="state">
  서버의 상태 (State)
</h2>

- `ok` 정상
- `reported` 일시 정지
- `blocked` 강제 삭제
- `unreachable` 정보를 불러올 수 없음 (서버에서 봇이 추방 or 봇이 오프라인)

<h2 id="flags">
  서버 플래그(flags)
</h2>

| VALUE  | DESCRIPTION                      |
| ------ | -------------------------------- |
| 0 << 0 | 없음                             |
| 1 << 0 | 공식 서버                        |
| 1 << 2 | 한국 디스코드 리스트 인증된 서버 |
| 1 << 3 | 한국 디스코드 리스트 파트너 서버 |
| 1 << 4 | 디스코드 인증된 서버             |
| 1 << 5 | 디스코드 파트너 서버             |

## 서버 정보 가져오기

### `GET` /v2/servers/{server.id}

[서버 정보](#server)를 반환합니다.

#### 응답 예시

```json
{
  "code": 200,
  "data": {
    "id": "653083797763522580",
    "name": "한국 디스코드 리스트",
    "flags": 5,
    "intro": "한국 디스코드 리스트 공식 디스코드입니다.",
    "desc": "\n# 한국 디스코드 리스트 :koreanbots:\n\n해당 웹사이트인 한국 디스코봇 리스트의 공식 디스코드입니다.\n\n## ✏️ 소개\n\n개발에 대해 질문하시거나 한국 디스코드 리스트에 관한 지원을 받을 수 있습니다.\n\n## 🔗 관련 링크\n\n- [Github](https://github.com/koreanbots)\n- [Twitter](https://twitter.com/koreanbots)",
    "votes": 6,
    "category": ["커뮤니티", "봇", "IT & 과학"],
    "invite": "JEh53MQ",
    "state": "ok",
    "vanity": "koreanlist",
    "bg": null,
    "banner": null,
    "icon": "873c83cf2ac50d4267e203f41dce60dd",
    "members": 2434,
    "emojis": [
      {
        "id": "653893296837623818",
        "name": "bot",
        "url": "https://cdn.discordapp.com/emojis/653893296837623818.png"
      },
      ...
    ],
    "boostTier": 3,
    "owner": {
      "id": "288302173912170497",
      "flags": 1,
      "github": "eunwoo1104",
      "tag": "9600",
      "username": "eunwoo1104",
      "bots": [
        "622710354836717580",
        "653534001742741552",
        "791679306123968553",
        "846571345847648336",
        "865107637288304682",
        "872349051620831292"
      ],
      "servers": [
        "653083797763522580",
        "653865550157578251",
        "807561475014262785",
        "880457187506421810",
        "911676954317582368",
        "937724514509422632"
      ]
    },
    "bots": [ ... ]
  },
  "version": 2
}
```

## 서버 검색하기

### `GET` /v2/search/servers

#### Query String

| FIELD | TYPE    | DESCRIPTION             |
| ----- | ------- | ----------------------- |
| query | string  | 검색어                  |
| page  | integer | 페이지 번호 (기본값: 1) |

#### 요청 예시

`GET` /v2/search/servers?query=한국+디스코드+리스트&page=1

#### 응답예시

```json
{
  "code": 200,
  "data": {
    "type": "SEARCH",
    "data": [
      {
        "id": "807561475014262785",
        "name": "한국 디스코드 리스트 채용",
        "flags": 5,
        "intro": "한국 디스코드 리스트 채용 디스코드 입니다.",
        "desc": "\n# 한국 디스코드 리스트 채용 :koreanbots:\n\n> 한국 디스코드 리스트 팀에 합류하고 싶으신가요?\n\n> 열정이 가득한 여러분을 기다리고 있습니다!\n\n> [모집 공고 보기](https://contents.koreanbots.dev/careers)\n\n한국 디스코드 리스트 채용 디스코드 입니다!\n",
        "votes": 0,
        "category": ["IT & 과학", "봇"],
        "invite": "EtezBPAgnu",
        "state": "ok",
        "vanity": "careers",
        "bg": null,
        "banner": null,
        "icon": "acef8a27d65b8059f294f0e039c9d8b0",
        "members": 79,
        "emojis": [],
        "boostTier": 0,
        "owner": {
          "id": "288302173912170497",
          "flags": 1,
          "github": "eunwoo1104",
          "tag": "9600",
          "username": "eunwoo1104",
          "bots": [
            "622710354836717580",
            "653534001742741552",
            "791679306123968553",
            "846571345847648336",
            "865107637288304682",
            "872349051620831292"
          ],
          "servers": [
            "653083797763522580",
            "653865550157578251",
            "807561475014262785",
            "880457187506421810",
            "911676954317582368",
            "937724514509422632"
          ]
        }
      }
    ],
    "currentPage": 1,
    "totalPage": 1
  },
  "version": 2
}
```

## 서버 관리자 불러오기

### `GET` /v2/servers/{server.id}/owners

#### 응답 예시

```json
{
  "code": 200,
  "data": [
    {
      "id": "285185716240252929",
      "flags": 7,
      "github": "wonderlandpark",
      "tag": "9999",
      "username": "wonderlandpark",
      "bots": [
        "387548561816027138",
        "530171799980212244",
        "653534001742741552",
        "676056487709245450",
        "707156018261524510",
        "707972925181001868",
        "762980393829269507",
        "784618064167698472"
      ],
      "servers": [
        "653083797763522580",
        "807561475014262785",
        "878610195004153897"
      ]
    },
    ...
  ],
  "version": 2
}
```

## 유저 서버 투표 여부 확인

### `GET` /v2/servers/{server.id}/vote

#### Request Header

| FIELD         | TYPE   | DESCRIPTION |
| ------------- | ------ | ----------- |
| Authorization | string | 서버의 토큰 |

#### Query String

| FIELD  | TYPE   | DESCRIPTION        |
| ------ | ------ | ------------------ |
| userID | string | 확인할 유저 아이디 |

#### 반환값

- `voted` 12시간이내 투표 여부
- `lastVote` 가장 최근 투표 시간 (timestamp)

#### 요청 예시

`GET` /v2/servers/653083797763522580/vote?userID=285185716240252929

##### Headers

```
Authorization: SUPER_SECRET_KOREANBOTS_TOKEN
Content-Type: application/json
```

#### 응답 예시

```json
{
  "code": 200,
  "data": {
    "voted": true,
    "lastVote": 1620183276602
  },
  "version": 2
}
```

위젯

# 위젯

## 봇 위젯 가져오기

### `GET` /widget/bots/{widget.type}/{bot.id}.svg

### widget.type
- `votes` 하트 수 위젯
- `servers` 서버 수 위젯
- `status` 봇 상태 위젯

### Query String

| FIELD | TYPE | DESCRIPTION | REQUIRED | DEFAULT |
|-------|------|-------------|----------|---------|
| style | `classic` 또는 `flat` | 위젯 타입 | false | flat |
| scale | number | 위젯 사이즈 (0.5~3.0) | false | 1.0 |
| icon | boolean | 봇 이미지 표시 여부 | false | true |

### 예시



- https://koreanbots.dev/api/widget/bots/status/653534001742741552.svg

![](https://koreanbots.dev/api/widget/bots/status/653534001742741552.svg)

- https://koreanbots.dev/api/widget/bots/servers/653534001742741552.svg?icon=false&scale=2

![](https://koreanbots.dev/api/widget/bots/servers/653534001742741552.svg?icon=false&scale=2)

- https://koreanbots.dev/api/widget/bots/votes/653534001742741552.svg?style=classic

![](https://koreanbots.dev/api/widget/bots/votes/653534001742741552.svg?style=classic)


## 서버 위젯 가져오기


### `GET` /widget/servers/{widget.type}/{server.id}.svg

### widget.type
- `votes` 하트 수 위젯
- `members` 멤버 수 위젯
- `boost` 부스트 티어 위젯

### Query String

| FIELD | TYPE | DESCRIPTION | REQUIRED | DEFAULT |
|-------|------|-------------|----------|---------|
| style | `classic` 또는 `flat` | 위젯 타입 | false | flat |
| scale | number | 위젯 사이즈 (0.5~3.0) | false | 1.0 |
| icon | boolean | 서버 이미지 표시 여부 | false | true |

### 예시

- https://koreanbots.dev/api/widget/servers/members/653083797763522580.svg

![](https://koreanbots.dev/api/widget/servers/members/653083797763522580.svg)

- https://koreanbots.dev/api/widget/servers/boost/653083797763522580.svg?icon=false&scale=2

![](https://koreanbots.dev/api/widget/servers/boost/653083797763522580.svg?icon=false&scale=2)

- https://koreanbots.dev/api/widget/servers/votes/653083797763522580.svg?style=classic

![](https://koreanbots.dev/api/widget/servers/votes/653083797763522580.svg?style=classic)

유저

# 유저

<h2 id="user">유저 정보</h2>

### 구조

| FIELD | TYPE | DESCRIPTION |
|-------|------|-------------|
| id | string | 유저의 ID |
| username | string | 유저의 디스코드 사용자 이름 |
| tag | string | 유저의 디스코드 태그 |
| github | ?string | 깃허브 닉네임 |
| flags | integer | 유저의 [플래그](#flags) |
| bots | [Bot](./봇#bot)[] | 소유한 봇들 (단, 소유자는 아이디만 표시됩니다) |
| servers | [Server](./서버#server)[] | 소유한 서버들 |

<h2 id="flags">유저 플래그(flags)</h2>

| VALUE | DESCRIPTION |
|-------|-------------|
| 0 << 0 | 없음 |
| 1 << 0 | 관리자 |
| 1 << 1 | 버그 헌터 |
| 1 << 2 | 봇 리뷰어 |
| 1 << 3 | 프리미엄 유저 |

## 유저 정보 가져오기

### `GET` /v2/users/{user.id}

[유저 정보](#user)를 반환합니다.

#### 응답 예시

```json
{
  "code": 200,
  "data": {
    "id": "285185716240252929",
    "flags": 1,
    "github": "wonderlandpark",
    "tag": "9999",
    "username": "wonderlandpark",
    "bots": [
      {
        "id": "653534001742741552",
        "flags": 4,
        "owners": [
          "285185716240252929"
        ],
        "lib": "discord.js",
        "prefix": "!",
        "votes": 39,
        "servers": 1,
        "intro": "디코봇 리스트 커뮤니티를 관리하기 위한 봇입니다. 공개봇이 아니며, 개인서버에서 사용하실 수 없어요!",
        "desc": "# IU BOT\n![Votes](https://api.koreanbots.dev/widget/bots/votes/653534001742741552.svg)\n## 해당봇은 특수목적용봇입니다.\n\n따로 서버로 초대하거나 사용하실 수 없습니다.\n\n## 목적\n\nKOREANBOTS 사이트의 봇 신청 처리 및 데이터 수정 등을 담당합니다.\n\n## 기능\n\n- approve\n- deny\n- edit\n- todo\n- ...",
        "web": "https://koreanbots.dev",
        "git": "https://github.com/koreanbots",
        "url": "",
        "category": [
          "관리",
          "로깅"
        ],
        "status": "online",
        "discord": "JEh53MQ",
        "state": "private",
        "vanity": "iu",
        "bg": "https://i.imgur.com/mFegdF1.jpg",
        "banner": "https://i.imgur.com/jcn4zaX.jpeg",
        "tag": "2833",
        "avatar": "3c986f863d0c45a329297425c4cbba4e",
        "name": "IU"
      },
      {
        "id": "784618064167698472",
        "flags": 4,
        "owners": [
          "285185716240252929"
        ],
        "lib": "discord.js",
        "prefix": "N/A",
        "votes": 4,
        "servers": 0,
        "intro": "한국 디스코드 서버 리스트 공식봇입니다.",
        "desc": "# 개발중입니다.\n\n아직 만나보실 수 없어요 조금만 기다려주세요!\n\n",
        "web": "https://koreanbots.dev/servers",
        "git": null,
        "url": null,
        "category": [
          "웹 대시보드",
          "유틸리티"
        ],
        "status": "offline",
        "discord": null,
        "state": "private",
        "vanity": "koreanservers",
        "bg": null,
        "banner": null,
        "tag": "1435",
        "avatar": "3a00d117f9ccbf469c20d8a9dc7b588c",
        "name": "한국 디스코드 서버 리스트"
      }
    ]
  },
  "version": 2
}
```


엔드포인트

# SDK 예시
언어별 SDK 예시는 각각의 SDK 문서에서 확인하실 수 있습니다.

## Python
[문서 링크](https://koreanbots.readthedocs.io/en/latest/intro.html#id4)

## Javascript
[문서 링크](https://js-sdk-docs.pages.dev/#%EC%82%AC%EC%9A%A9%EB%B2%95)
