Bot API

Read and change what Sample Bot does in a server, from your own code. 103 endpoints across 17 areas, plus 65 webhook events.

https://api.samplebot.app/v1/servers/{server id}/...

Connecting a server

A key on its own reaches nothing. For your application to work on a server:

Give the server's admin your application ID (on Your application).
They open config.samplebot.app, pick the server, open API, paste the ID and tick what your application may do.
Your application can now call that server, for those things only. GET /v1/me lists the servers it is connected to.

The admin can change the ticks or disconnect your application at any time. Everything your application changes appears in the server's audit log as via API: your application's name, and actions are done in the name of the admin who connected it.

Where an action needs a person (claiming or closing a ticket), you name them with userId, and their own permissions are checked, exactly as if they pressed the button.

Permissions (scopes)

Scope	Lets the application
`server:read`	See the server name, member count, channels and roles
`sessions:read`	See sessions and session votes
`sessions:write`	Start, change and end sessions and votes
`shifts:read`	See shifts, who is on duty and the leaderboard
`shifts:write`	Start and end shifts, breaks, and add time
`tickets:read`	See tickets
`tickets:write`	Claim, unclaim and close tickets
`moderation:read`	See moderation cases and in-game moderation
`moderation:write`	Warn members, file in-game kicks and bans, decide BOLOs
`cad:read` Plus	See CAD calls, units, records and characters
`cad:write` Plus	Create calls and records, change unit status
`erlc:read`	See the game server, players and logs
`erlc:write`	Run commands in the game server
`regions:read`	See areas and who is in them
`regions:write`	Draw and delete areas
`automations:read`	See automations
`automations:write` Plus	Run automations and switch them on or off
`applications:read`	See application forms and submissions
`applications:write`	Accept and deny applications
`members:read`	Look up members and their linked Roblox accounts
`giveaways:read`	See giveaways
`giveaways:write`	End and reroll giveaways
`loa:read`	See leave of absence
`loa:write`	Approve and deny leave
`suggestions:read`	See suggestions
`suggestions:write`	Approve and deny suggestions
`staff:read`	See staff requests, trainings, activity checks and roleplay requests
`staff:write`	Approve and deny roleplay requests
`directory:read`	See this server's directory listing
`audit:read`	See this server's audit log

Example

// Who is on shift right now?
const res = await fetch("https://api.samplebot.app/v1/servers/" + SERVER_ID + "/shifts/active", {
  headers: { Authorization: `Bearer ${process.env.SAMPLE_API_KEY}` },
});
const { ok, data, error } = await res.json();
if (!ok) throw new Error(error.message);
console.log(data);

Endpoints

Server

GET `/`	The server: name, members, Plus, and what this app may do here.
GET `/channels`	Text channels the bot can see.
GET `/roles`	Roles, highest first.
GET `/features`	Which Sample Bot features are switched on.

Sessions and votes

GET `/sessions/active`	The session running now, or null.
GET `/sessions`	Past and present sessions, newest first.
GET `/sessions/:id`	One session.
POST `/sessions/start`	Start a session in the session channel.
POST `/sessions/status`	Mark the session ACTIVE, FULL or BOOST.
POST `/sessions/end`	End the session (and any open vote).
GET `/votes/active`	Open session votes, with how many have voted.
GET `/votes`	Past votes, newest first.
POST `/votes/start`	Open a public session vote.
POST `/votes/:id/cancel`	Call a vote off.

Shifts

GET `/shifts/active`	Who is on shift or on break right now.
GET `/shifts`	Shifts, newest first. Filter by userId.
GET `/shifts/leaderboard`	This week's time on duty, most first.
GET `/shifts/users/:userId`	One person: their open shift and this week's total.
POST `/shifts/start`	Put someone on shift.
POST `/shifts/end`	End someone's shift.
POST `/shifts/break/start`	Put someone on break.
POST `/shifts/break/end`	Bring someone back from break.
POST `/shifts/credit`	Add time to someone's week.

Tickets

GET `/tickets`	Tickets. Open and claimed by default; status=CLOSED for closed ones.
GET `/tickets/stats`	Counts: open, claimed, closed this week.
GET `/tickets/:id`	One ticket.
POST `/tickets/:id/claim`	Claim a ticket as a staff member. Their own permissions are checked.
POST `/tickets/:id/unclaim`	Let a claimed ticket go.
POST `/tickets/:id/close`	Close a ticket with a transcript, as a staff member allowed to.

Moderation

GET `/cases`	Moderation cases, newest first. Filter by userId or kind.
GET `/cases/:number`	One case, by its number.
GET `/cases/users/:userId`	Someone's record: every case and a count by kind.
POST `/cases/warn`	Warn a member. Logged and sent to them like a /warn.
POST `/cases/:number/void`	Void a case.
GET `/game-moderation`	In-game warnings, kicks, bans and BOLOs filed through Sample Bot.
POST `/game-moderation`	File an in-game warning, kick, ban or BOLO. Kicks and bans run in the game.
GET `/game-moderation/bolos`	BOLOs waiting for a decision.
POST `/game-moderation/bolos/:id/approve`	Approve a BOLO, which bans the player in game.
POST `/game-moderation/bolos/:id/decline`	Decline a BOLO.

CAD (Plus)

GET `/cad/calls`	Open calls. closed=true to include closed ones.
GET `/cad/calls/:id`	One call, with its units and notes.
POST `/cad/calls`	Create a call on the board.
POST `/cad/calls/:id/notes`	Add a note to a call.
POST `/cad/calls/:id/close`	Close a call and free its units.
POST `/cad/calls/:id/assign`	Attach a unit to a call.
GET `/cad/units`	Units signed on now.
GET `/cad/units/:id`	One unit.
POST `/cad/units/:id/status`	Change a unit's status (10-8, 10-6, 10-7, 10-97, 10-23, 10-11, 10-15).
GET `/cad/alerts`	Active warrants and BOLOs.
GET `/cad/records`	Records, newest first. Filter by citizenId, kind or plate.
GET `/cad/records/:id`	One record.
POST `/cad/records`	Write a record: citation, arrest, warrant, BOLO or incident.
GET `/cad/search`	Search characters, plates and records.
GET `/cad/citizens/:id`	One character with licences, vehicles and records.
GET `/cad/plates/:plate`	Run a plate.
GET `/cad/feed`	The CAD's live feed: joins, downs, stops, mod calls (last 7 days).
GET `/cad/bodycams`	Recent bodycam recordings and who they belong to.

In game (ER:LC)

GET `/erlc/server`	The game server: name, code, players, queue.
GET `/erlc/players`	Players in game, with team and callsign.
GET `/erlc/positions`	Where each player is on the map, with the nearest postal.
GET `/erlc/queue`	Players waiting to join.
GET `/erlc/vehicles`	Spawned vehicles.
GET `/erlc/joins`	Join and leave log.
GET `/erlc/kills`	Kill log.
GET `/erlc/commands`	Command log.
GET `/erlc/modcalls`	Mod call log.
GET `/erlc/bans`	Players banned from the game server.
POST `/erlc/command`	Run a command in the game server, for example ":h Server restart in 5 minutes".

Areas

GET `/regions`	Areas drawn on the map.
GET `/regions/:id`	One area, with who is in it now.
POST `/regions`	Draw an area from map points.
DELETE `/regions/:id`	Delete an area.

Automations

GET `/automations`	Automations in this server.
GET `/automations/:number`	One automation.
POST `/automations/:number/run`	Run an automation now, with optional values for its text.
POST `/automations/:number/enabled`	Switch an automation on or off.

Applications

GET `/applications`	Application forms.
GET `/applications/submissions`	Submissions. status=PENDING, ACCEPTED or DENIED.
GET `/applications/submissions/:id`	One submission with its answers.
POST `/applications/submissions/:id/decide`	Accept or deny. Roles and messages happen as they do in Discord.

Members

GET `/members/:userId`	A member: name, roles, when they joined, their Roblox account.
GET `/members/by-roblox/:robloxId`	Which member of this server owns a Roblox account. Only members of this server are found.
GET `/members/by-roblox-name/:name`	The same, by Roblox username.

Giveaways

GET `/giveaways`	Giveaways, running first.
GET `/giveaways/:id`	One giveaway.
POST `/giveaways/:id/end`	End a giveaway now and pick winners.
POST `/giveaways/:id/reroll`	Pick new winners.

Leave of absence

GET `/loa`	Who is on leave now.
GET `/loa/requests`	Leave requests waiting for a decision.
GET `/loa/users/:userId`	Someone's leave history.
POST `/loa/:id/decide`	Approve or deny a leave request.
POST `/loa/:id/end`	End someone's leave early.

Suggestions

GET `/suggestions`	Suggestions, newest first. status=PENDING, APPROVED or DENIED.
GET `/suggestions/:id`	One suggestion with its votes.
POST `/suggestions/:id/review`	Approve or deny a suggestion.

Staff team

GET `/staff/requests`	Recent calls for staff in game.
GET `/staff/trainings`	Trainings, newest first.
GET `/staff/activity-checks`	Activity checks, newest first.
GET `/staff/activity-checks/:id`	One activity check: who answered and who has not.
GET `/roleplay-requests`	Roleplay requests. status=PENDING, APPROVED or DENIED.
POST `/roleplay-requests/:id/decide`	Approve or deny a roleplay request.

Audit log

GET /audit The server's audit log, including what apps did.

Not in the API, on purpose

Bumping and voting in the server directory, giving out staff permissions in game, and changing the bot's setup. These stay with people in Discord.

Open this on a computer