# API

Welcome to the Soldier API.
You can create awesome things with Soldier, let's get you started.

# Obtaining API Keys

In order to use the Soldier API, you must obtain an authentication token from the guild.
This can be quickly retrieved from the bot, or using the online dashboard.

Use the /settings option: Group command.
Press the button to view the API Settings for this server.

Now you should be able to generate an API token to use in your application.

Once you generate a token, you will only be able to see it once.
Make sure to copy it and keep it in a safe location.

Navigate to the Dashboard at dash.soldierbot.app.
Continue through the Discord authorization flow, logging in using your Discord account.

Select the server you wish to manage, then scroll to the API section.
From there, you can generate and regenerate tokens as you wish.

Once you generate an API token, the API will automatically be enabled by default.
You can change this setting freely as you wish, to disable the use of the API.

# Authentication

The Soldier API contains a public route: /users
Which does not require guild authentication.

And some private API routes: /guild /events /medals /rank /xp
Which do require guild authentication.

# Request Headers

Requests sent to these private API routes require an authorization token in the request header:

authentication: The bearer token contained in your authentication string
Example: Soldier HCYrY1MsaB2fd13

# Routes

Base URL: https://api.soldierbot.app/v1/
/guild: Shows information about the currently authenticated group.
/event: Create and manage events used for Soldier
/medals: Create and manage medals and their recipients
/rank: Rank users within your group
/users: Get information about a user
/xp: Manage user xp in your group

# Responses

# Response Codes

: Something went wrong on our end
: Invalid API credentials were received
: The operation couldn't initiate due to a malformed request body
: A resource from your request body wasn't found
: The operation initiated, the response body indicates whether it succeeded or not

# Body Schema

{
  success: boolean;            // Whether the complete operation succeeded
  status: string;              // The status of the response, indicated by the codes above
  data: any | undefined;       // Data about the completed operation
  message: string | undefined; // A message about what went wrong
}

# Types

type RankerId = number.int().positive()?; // User who made the request
type RobloxId = number.int().positive(); // User being ranked
type GroupRank = number.int().min(0).max(255); // Group rank
type GuildAuthToken = string; // Guild authentication token
type RelativeRank = number.int().min(1).max(5); // How many ranks up or down to change