BotGG
EN
Open console Add to Discord

REST API v1 · Developers · API reference

Applications API reference

All 4 Applications endpoints of the BotGG REST API v1: scopes, parameters, fields, errors and ready-to-run curl, JavaScript and Python examples.

Updated: OpenAPI 3.1 (JSON)

Developer docs
On this page

Endpoints

Paths are relative to https://console.botgg.app/api/v1. Send your API key as Authorization: Bearer botgg_…; IDs are strings.

Applications endpoints
EndpointScopeDescription
GET/guilds/{guildId}/applications/formsapplications:readList application forms
GET/guilds/{guildId}/applications/submissionsapplications:readList applications
GET/guilds/{guildId}/applications/submissions/{number}applications:readGet an application
POST/guilds/{guildId}/applications/submissions/{number}/decisionapplications:writeAccept or deny an application

Besides its own errors below, every endpoint can return these common ones:

Errors
HTTPCodes
400INVALID_REQUEST
401UNAUTHORIZED, INVALID_API_KEY, API_KEY_REVOKED, API_KEY_EXPIRED
403BROWSER_REQUESTS_NOT_ALLOWED, GUILD_MISMATCH, INSUFFICIENT_SCOPE, GUILD_BLOCKED
404BOT_NOT_IN_GUILD
429RATE_LIMITED
500INTERNAL

List application forms

GET/guilds/{guildId}/applications/forms

Scope: applications:read

In the console’s order, with their questions and submission counts.

Needs this feature enabled on the server: Applications

Parameters
NameInTypeRequiredDescription
guildIdpathstringYesYour server’s ID · Discord ID (string)

Response

Response fields · 200
FieldTypeRequiredDescription
itemsarray of objectYes
items[].idintegerYes
items[].titlestringYes
items[].descriptionstringYes
items[].openbooleanYesThe open toggle (the open window is in opensAt / closesAt)
items[].opensAtstring | nullYesISO 8601 date-time
items[].closesAtstring | nullYesISO 8601 date-time
items[].questionsarray of objectYes
items[].questions[].idstringYes
items[].questions[].typestringYes
items[].questions[].labelstringYes
items[].questions[].requiredbooleanYes
items[].submissionsobjectYes
items[].submissions.totalintegerYes
items[].submissions.openintegerYes
Response · 200
{
  "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
      }
    }
  ]
}

Examples

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/applications/forms" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// 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);
Python (requests)
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)

Errors

Errors
HTTPCodes
409FEATURE_DISABLED
503SERVICE_UNAVAILABLE

List applications

GET/guilds/{guildId}/applications/submissions

Scope: applications:read

Newest first, without answers. status=open = pending + interview + hold, decided = accepted + denied. Pass before=<nextCursor> for the next page.

Needs this feature enabled on the server: Applications

Parameters
NameInTypeRequiredDescription
guildIdpathstringYesYour server’s ID · Discord ID (string)
statusquerystringNoOne of pending, interview, hold, accepted, denied, withdrawn, open, decided
formIdqueryintegerNoat least 1
userIdquerystringNoOnly this applicant
Discord ID (string)
limitqueryintegerNo1–100 · Default 25
beforequeryintegerNo1–999,999,999

Response

Response fields · 200
FieldTypeRequiredDescription
itemsarray of objectYes
items[].numberintegerYes
items[].formIdinteger | nullYesnull when the form was deleted
items[].formTitlestring | nullYes
items[].userIdstringYes
items[].statusstringYesOne of pending, interview, hold, accepted, denied, withdrawn
items[].votesobjectYes
items[].votes.upintegerYes
items[].votes.downintegerYes
items[].submittedAtstring | nullYesISO 8601 date-time
items[].decidedAtstring | nullYesISO 8601 date-time
items[].decidedBystring | nullYesnull = system / API
items[].reasonstring | nullYes
nextCursorstring | nullYes
Response · 200
{
  "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"
}

Examples

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/applications/submissions?limit=25" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// 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);
Python (requests)
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)

Errors

Errors
HTTPCodes
409FEATURE_DISABLED
503SERVICE_UNAVAILABLE

Get an application

GET/guilds/{guildId}/applications/submissions/{number}

Scope: applications:read

With the answers and the applicant snapshot taken at submit time (account age, join date, roles, level).

Needs this feature enabled on the server: Applications

Parameters
NameInTypeRequiredDescription
guildIdpathstringYesYour server’s ID · Discord ID (string)
numberpathstringYes

Response

Response fields · 200
FieldTypeRequiredDescription
numberintegerYes
formIdinteger | nullYesnull when the form was deleted
formTitlestring | nullYes
userIdstringYes
statusstringYesOne of pending, interview, hold, accepted, denied, withdrawn
votesobjectYes
votes.upintegerYes
votes.downintegerYes
submittedAtstring | nullYesISO 8601 date-time
decidedAtstring | nullYesISO 8601 date-time
decidedBystring | nullYesnull = system / API
reasonstring | nullYes
answersarray of objectYes
answers[].idstringYes
answers[].typestringYes
answers[].labelstringYes
answers[].textstringYes
applicantobjectYes
applicant.accountCreatedAtstring | nullYesISO 8601 date-time
applicant.joinedAtstring | nullYesISO 8601 date-time
applicant.roleIdsarray of stringYes
applicant.levelinteger | nullYes
applyingbooleanYesA console/API decision is still being applied in Discord
failedActionsarray of objectYes
failedActions[].typestringYes
failedActions[].errorstring | nullYes
Response · 200
{
  "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"
    }
  ]
}

Examples

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/applications/submissions/234567890123456789" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// 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);
Python (requests)
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)

Errors

Errors
HTTPCodes
404APPLICATION_NOT_FOUND
409FEATURE_DISABLED
503SERVICE_UNAVAILABLE

Accept or deny an application

POST/guilds/{guildId}/applications/submissions/{number}/decision

Scope: applications:writeIdempotency-Key

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.

Needs this feature enabled on the server: Applications

Parameters
NameInTypeRequiredDescription
guildIdpathstringYesYour server’s ID · Discord ID (string)
numberpathstringYes
Idempotency-KeyheaderstringNoOptional. Send a unique value (a UUID) and reuse it when you retry: the change happens only once. How it works

Request body

Request body
FieldTypeRequiredDescription
decisionstringYesOne of accepted, denied
reasonstring | nullNoSent to the applicant (DM) and shown in the review
up to 1,000 characters

Response

Response fields · 202
FieldTypeRequiredDescription
numberintegerYes
formIdinteger | nullYesnull when the form was deleted
formTitlestring | nullYes
userIdstringYes
statusstringYesOne of pending, interview, hold, accepted, denied, withdrawn
votesobjectYes
votes.upintegerYes
votes.downintegerYes
submittedAtstring | nullYesISO 8601 date-time
decidedAtstring | nullYesISO 8601 date-time
decidedBystring | nullYesnull = system / API
reasonstring | nullYes
answersarray of objectYes
answers[].idstringYes
answers[].typestringYes
answers[].labelstringYes
answers[].textstringYes
applicantobjectYes
applicant.accountCreatedAtstring | nullYesISO 8601 date-time
applicant.joinedAtstring | nullYesISO 8601 date-time
applicant.roleIdsarray of stringYes
applicant.levelinteger | nullYes
applyingbooleanYesA console/API decision is still being applied in Discord
failedActionsarray of objectYes
failedActions[].typestringYes
failedActions[].errorstring | nullYes
Response · 202
{
  "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"
    }
  ]
}

Examples

curl
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"}'
JavaScript (fetch)
// 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);
Python (requests)
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)

Errors

Errors
HTTPCodes
400INVALID_JSON
403SELF_DECISION
404APPLICATION_NOT_FOUND
409FEATURE_DISABLED, ALREADY_DECIDED
413PAYLOAD_TOO_LARGE
415UNSUPPORTED_MEDIA_TYPE
422IDEMPOTENCY_KEY_REUSED
503SERVICE_UNAVAILABLE

Ready to level up your server?

Add BotGG for free, then switch features on in the web console.

Add to DiscordOpen the console