REST API v1 · 開發者 · API 參考
申請 API 參考
BotGG REST API v1 的所有 4 個 申請 端點:範圍、參數、欄位、錯誤,以及可直接執行的 curl、JavaScript 與 Python 範例。
開發者文件
本頁目錄
端點
路徑皆相對於 https://console.botgg.app/api/v1。請以 Authorization: Bearer botgg_… 傳送你的 API 金鑰,ID 皆為字串。
| 端點 | 範圍 | 說明 |
|---|---|---|
GET/guilds/{guildId}/applications/forms | applications:read | List application forms |
GET/guilds/{guildId}/applications/submissions | applications:read | List applications |
GET/guilds/{guildId}/applications/submissions/{number} | applications:read | Get an application |
POST/guilds/{guildId}/applications/submissions/{number}/decision | applications:write | Accept or deny an application |
除了下方各自的錯誤外,每個端點還可能回傳這些常見錯誤:
List application forms
GET/guilds/{guildId}/applications/forms
In the console’s order, with their questions and submission counts.
需要在伺服器上啟用此功能: 申請
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
items | array of object | 是 | |
items[].id | integer | 是 | |
items[].title | string | 是 | |
items[].description | string | 是 | |
items[].open | boolean | 是 | The open toggle (the open window is in opensAt / closesAt) |
items[].opensAt | string | null | 是 | ISO 8601 date-time |
items[].closesAt | string | null | 是 | ISO 8601 date-time |
items[].questions | array of object | 是 | |
items[].questions[].id | string | 是 | |
items[].questions[].type | string | 是 | |
items[].questions[].label | string | 是 | |
items[].questions[].required | boolean | 是 | |
items[].submissions | object | 是 | |
items[].submissions.total | integer | 是 | |
items[].submissions.open | integer | 是 |
{
"items": [
{
"id": 98765,
"title": "example",
"description": "example",
"open": true,
"opensAt": "2026-10-07T12:00:00.000Z",
"closesAt": "2026-10-07T12:00:00.000Z",
"questions": [
{
"id": "example",
"type": "example",
"label": "Example",
"required": true
}
],
"submissions": {
"total": 10,
"open": 10
}
}
]
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/applications/forms" \
-H "Authorization: Bearer $BOTGG_API_KEY"// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/applications/forms', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
},
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);import os
import requests
res = requests.get(
"https://console.botgg.app/api/v1/guilds/123456789012345678/applications/forms",
headers={
"Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)錯誤
| HTTP | 代碼 |
|---|---|
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
List applications
GET/guilds/{guildId}/applications/submissions
Newest first, without answers. status=open = pending + interview + hold, decided = accepted + denied. Pass before=<nextCursor> for the next page.
需要在伺服器上啟用此功能: 申請
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
status | 查詢字串 | string | 否 | 其中之一 pending, interview, hold, accepted, denied, withdrawn, open, decided |
formId | 查詢字串 | integer | 否 | 至少 1 |
userId | 查詢字串 | string | 否 | Only this applicant Discord ID(字串) |
limit | 查詢字串 | integer | 否 | 1–100 · 預設值 25 |
before | 查詢字串 | integer | 否 | 1–999,999,999 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
items | array of object | 是 | |
items[].number | integer | 是 | |
items[].formId | integer | null | 是 | null when the form was deleted |
items[].formTitle | string | null | 是 | |
items[].userId | string | 是 | |
items[].status | string | 是 | 其中之一 pending, interview, hold, accepted, denied, withdrawn |
items[].votes | object | 是 | |
items[].votes.up | integer | 是 | |
items[].votes.down | integer | 是 | |
items[].submittedAt | string | null | 是 | ISO 8601 date-time |
items[].decidedAt | string | null | 是 | ISO 8601 date-time |
items[].decidedBy | string | null | 是 | null = system / API |
items[].reason | string | null | 是 | |
nextCursor | string | null | 是 |
{
"items": [
{
"number": 7,
"formId": 98765,
"formTitle": "example",
"userId": "876543210987654321",
"status": "pending",
"votes": {
"up": 10,
"down": 10
},
"submittedAt": "2026-10-07T12:00:00.000Z",
"decidedAt": "2026-10-07T12:00:00.000Z",
"decidedBy": "example",
"reason": "Tournament prize"
}
],
"nextCursor": "98700"
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/applications/submissions?limit=25" \
-H "Authorization: Bearer $BOTGG_API_KEY"// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/applications/submissions?limit=25', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
},
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);import os
import requests
res = requests.get(
"https://console.botgg.app/api/v1/guilds/123456789012345678/applications/submissions",
headers={
"Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
},
params={
"limit": 25,
},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)錯誤
| HTTP | 代碼 |
|---|---|
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
Get an application
GET/guilds/{guildId}/applications/submissions/{number}
With the answers and the applicant snapshot taken at submit time (account age, join date, roles, level).
需要在伺服器上啟用此功能: 申請
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
number | 路徑 | string | 是 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
number | integer | 是 | |
formId | integer | null | 是 | null when the form was deleted |
formTitle | string | null | 是 | |
userId | string | 是 | |
status | string | 是 | 其中之一 pending, interview, hold, accepted, denied, withdrawn |
votes | object | 是 | |
votes.up | integer | 是 | |
votes.down | integer | 是 | |
submittedAt | string | null | 是 | ISO 8601 date-time |
decidedAt | string | null | 是 | ISO 8601 date-time |
decidedBy | string | null | 是 | null = system / API |
reason | string | null | 是 | |
answers | array of object | 是 | |
answers[].id | string | 是 | |
answers[].type | string | 是 | |
answers[].label | string | 是 | |
answers[].text | string | 是 | |
applicant | object | 是 | |
applicant.accountCreatedAt | string | null | 是 | ISO 8601 date-time |
applicant.joinedAt | string | null | 是 | ISO 8601 date-time |
applicant.roleIds | array of string | 是 | |
applicant.level | integer | null | 是 | |
applying | boolean | 是 | A console/API decision is still being applied in Discord |
failedActions | array of object | 是 | |
failedActions[].type | string | 是 | |
failedActions[].error | string | null | 是 |
{
"number": 7,
"formId": 98765,
"formTitle": "example",
"userId": "876543210987654321",
"status": "pending",
"votes": {
"up": 10,
"down": 10
},
"submittedAt": "2026-10-07T12:00:00.000Z",
"decidedAt": "2026-10-07T12:00:00.000Z",
"decidedBy": "example",
"reason": "Tournament prize",
"answers": [
{
"id": "example",
"type": "example",
"label": "Example",
"text": "Example answer"
}
],
"applicant": {
"accountCreatedAt": "2026-10-07T12:00:00.000Z",
"joinedAt": "2026-10-07T12:00:00.000Z",
"roleIds": [
"234567890123456789"
],
"level": 5
},
"applying": true,
"failedActions": [
{
"type": "example",
"error": "example"
}
]
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/applications/submissions/234567890123456789" \
-H "Authorization: Bearer $BOTGG_API_KEY"// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/applications/submissions/234567890123456789', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
},
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);import os
import requests
res = requests.get(
"https://console.botgg.app/api/v1/guilds/123456789012345678/applications/submissions/234567890123456789",
headers={
"Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)錯誤
| HTTP | 代碼 |
|---|---|
| 404 | APPLICATION_NOT_FOUND |
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
Accept or deny an application
POST/guilds/{guildId}/applications/submissions/{number}/decision
Same as Accept / Deny in the console: decided now (status, reason, reapply cooldown after a denial), then the bot gives / removes the form’s roles, DMs the applicant, announces and updates the review within a few seconds (applying). Written to the audit log.
需要在伺服器上啟用此功能: 申請
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
number | 路徑 | string | 是 | |
Idempotency-Key | 標頭 | string | 否 | 選填。傳送一個唯一值(UUID),重試時沿用同一個值,變更就只會發生一次。 運作方式 |
請求內容
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
decision | string | 是 | 其中之一 accepted, denied |
reason | string | null | 否 | Sent to the applicant (DM) and shown in the review 最多 1,000 個字元 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
number | integer | 是 | |
formId | integer | null | 是 | null when the form was deleted |
formTitle | string | null | 是 | |
userId | string | 是 | |
status | string | 是 | 其中之一 pending, interview, hold, accepted, denied, withdrawn |
votes | object | 是 | |
votes.up | integer | 是 | |
votes.down | integer | 是 | |
submittedAt | string | null | 是 | ISO 8601 date-time |
decidedAt | string | null | 是 | ISO 8601 date-time |
decidedBy | string | null | 是 | null = system / API |
reason | string | null | 是 | |
answers | array of object | 是 | |
answers[].id | string | 是 | |
answers[].type | string | 是 | |
answers[].label | string | 是 | |
answers[].text | string | 是 | |
applicant | object | 是 | |
applicant.accountCreatedAt | string | null | 是 | ISO 8601 date-time |
applicant.joinedAt | string | null | 是 | ISO 8601 date-time |
applicant.roleIds | array of string | 是 | |
applicant.level | integer | null | 是 | |
applying | boolean | 是 | A console/API decision is still being applied in Discord |
failedActions | array of object | 是 | |
failedActions[].type | string | 是 | |
failedActions[].error | string | null | 是 |
{
"number": 7,
"formId": 98765,
"formTitle": "example",
"userId": "876543210987654321",
"status": "pending",
"votes": {
"up": 10,
"down": 10
},
"submittedAt": "2026-10-07T12:00:00.000Z",
"decidedAt": "2026-10-07T12:00:00.000Z",
"decidedBy": "example",
"reason": "Tournament prize",
"answers": [
{
"id": "example",
"type": "example",
"label": "Example",
"text": "Example answer"
}
],
"applicant": {
"accountCreatedAt": "2026-10-07T12:00:00.000Z",
"joinedAt": "2026-10-07T12:00:00.000Z",
"roleIds": [
"234567890123456789"
],
"level": 5
},
"applying": true,
"failedActions": [
{
"type": "example",
"error": "example"
}
]
}範例
curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/applications/submissions/234567890123456789/decision" \
-H "Authorization: Bearer $BOTGG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"decision":"accepted","reason":"Tournament prize"}'// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/applications/submissions/234567890123456789/decision', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
},
body: JSON.stringify({
decision: 'accepted',
reason: 'Tournament prize',
}),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);import os, uuid
import requests
res = requests.post(
"https://console.botgg.app/api/v1/guilds/123456789012345678/applications/submissions/234567890123456789/decision",
headers={
"Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()), # reuse it when you retry this request
},
json={
"decision": "accepted",
"reason": "Tournament prize",
},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)