Evalyn HTTP API

Roblox module

Drop this ModuleScript into ServerScriptService (name it EvalynAPI), fill in your workspace and secret, and call it from your server scripts. Enable Allow HTTP Requests in Game Settings → Security first.

--!strict
-- EvalynAPI — ServerScriptService/EvalynAPI (ModuleScript)
local HttpService = game:GetService("HttpService")

local BASE = "https://evalyn.tacogroup.uk"
local WORKSPACE = "my-group"            -- your workspace slug or Roblox group ID
local API_SECRET = "PASTE_YOUR_SECRET"  -- Settings -> API. Keep server-side only!

local Evalyn = {}

local function request(path: string, method: string, body: any?)
	local ok, res = pcall(function()
		return HttpService:RequestAsync({
			Url = BASE .. path,
			Method = method,
			Headers = {
				["Authorization"] = "Bearer " .. API_SECRET,
				["Content-Type"] = "application/json",
			},
			Body = body and HttpService:JSONEncode(body) or nil,
		})
	end)
	if not ok then
		warn("[Evalyn] request failed:", res)
		return nil
	end
	if not res.Success then
		warn(("[Evalyn] %d %s"):format(res.StatusCode, tostring(res.Body)))
		return nil
	end
	if res.Body and res.Body ~= "" then
		local decoded
		pcall(function() decoded = HttpService:JSONDecode(res.Body) end)
		return decoded
	end
	return {}
end

function Evalyn.clockIn(userId: number, gameName: string?)
	return request("/api/handler/shifts", "POST", {
		action = "clock_in", workspace_slug = WORKSPACE,
		user_id = tostring(userId), game_name = gameName,
	})
end

function Evalyn.clockOut(userId: number, durationMinutes: number?)
	return request("/api/handler/shifts", "POST", {
		action = "clock_out", workspace_slug = WORKSPACE,
		user_id = tostring(userId), duration_minutes = durationMinutes,
	})
end

function Evalyn.syncShift(userId: number, durationMinutes: number)
	return request("/api/handler/shift-sync", "POST", {
		workspace_slug = WORKSPACE, user_id = tostring(userId),
		duration_minutes = durationMinutes,
	})
end

function Evalyn.playerJoined(userId: number)
	return request("/api/handler/activity", "POST", {
		workspace_slug = WORKSPACE, action = "player_joined", user_id = tostring(userId),
	})
end

function Evalyn.playerLeft(userId: number)
	return request("/api/handler/activity", "POST", {
		workspace_slug = WORKSPACE, action = "player_left", user_id = tostring(userId),
	})
end

function Evalyn.heartbeat(playerCount: number)
	return request("/api/handler/activity", "POST", {
		workspace_slug = WORKSPACE, action = "heartbeat", player_count = playerCount,
	})
end

function Evalyn.setAfk(userId: number, afk: boolean)
	return request("/api/handler/afk", "POST", {
		workspace_slug = WORKSPACE, user_id = tostring(userId),
		action = afk and "afk" or "active",
	})
end

function Evalyn.ban(playerId: number, reason: string?, bannedBy: number?)
	return request("/api/handler/ban", "POST", {
		workspace_slug = WORKSPACE, player_id = tostring(playerId),
		reason = reason, banned_by = bannedBy and tostring(bannedBy) or nil,
	})
end

function Evalyn.unban(playerId: number)
	return request("/api/handler/ban", "POST", {
		workspace_slug = WORKSPACE, player_id = tostring(playerId), action = "unban",
	})
end

function Evalyn.warnPlayer(userId: number, reason: string, warnedBy: string?)
	return request("/api/handler/warn", "POST", {
		workspace_slug = WORKSPACE, user_id = tostring(userId),
		reason = reason, warned_by = warnedBy,
	})
end

function Evalyn.logChat(userId: number, displayName: string, message: string)
	return request("/api/handler/chat", "POST", {
		workspace_slug = WORKSPACE, user_id = tostring(userId),
		display_name = displayName, message = message,
	})
end

function Evalyn.getStatus(userId: number)
	return request("/api/handler/status/" .. WORKSPACE .. "/" .. tostring(userId), "GET")
end

-- Returns { banned, blacklisted, action, reason, ... } for the player.
function Evalyn.check(userId: number)
	return request("/api/handler/check/" .. WORKSPACE .. "/" .. tostring(userId), "GET")
end

function Evalyn.blacklist(playerId: number, reason: string?, addedBy: number?)
	return request("/api/handler/blacklist", "POST", {
		workspace_slug = WORKSPACE, player_id = tostring(playerId),
		reason = reason, added_by = addedBy and tostring(addedBy) or nil,
	})
end

function Evalyn.unblacklist(playerId: number)
	return request("/api/handler/blacklist", "POST", {
		workspace_slug = WORKSPACE, player_id = tostring(playerId), action = "remove",
	})
end

return Evalyn

Using it (a Script in ServerScriptService)

local Players = game:GetService("Players")
local Evalyn = require(game.ServerScriptService.EvalynAPI)

Players.PlayerAdded:Connect(function(player)
	-- Enforce bans & blacklists on join.
	local verdict = Evalyn.check(player.UserId)
	if verdict and verdict.action == "kick" then
		player:Kick("You are " .. (verdict.banned and "banned" or "blacklisted")
			.. (verdict.reason and (": " .. verdict.reason) or "") .. ".")
		return
	end

	Evalyn.playerJoined(player.UserId)

	-- Log this player's chat (server-side, works with TextChatService).
	player.Chatted:Connect(function(message)
		Evalyn.logChat(player.UserId, player.DisplayName, message)
	end)
end)

Players.PlayerRemoving:Connect(function(player)
	Evalyn.playerLeft(player.UserId)
end)

-- Heartbeat every 60s
task.spawn(function()
	while task.wait(60) do
		Evalyn.heartbeat(#Players:GetPlayers())
	end
end)

Instant AFK when a player alt-tabs (optional)

Window focus is a client signal, so this needs two parts. On the server, create a RemoteEvent named EvalynAFK in ReplicatedStorage and forward it to Evalyn.setAfk:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local afk = ReplicatedStorage:FindFirstChild("EvalynAFK") or Instance.new("RemoteEvent")
afk.Name = "EvalynAFK"
afk.Parent = ReplicatedStorage
afk.OnServerEvent:Connect(function(player, focused)
	Evalyn.setAfk(player.UserId, not focused)
end)

Then add a LocalScript in StarterPlayer → StarterPlayerScripts:

local UserInputService = game:GetService("UserInputService")
local afk = game:GetService("ReplicatedStorage"):WaitForChild("EvalynAFK")

-- Fires the moment the player alt-tabs / clicks another app.
UserInputService.WindowFocusReleased:Connect(function() afk:FireServer(false) end)
UserInputService.WindowFocused:Connect(function() afk:FireServer(true) end)

The downloadable handler script already includes the server half — you only need to add the LocalScript.

REST API (API keys)

Separate from the game handler, workspaces can create API keys (the API Keys page) with scoped permissions for read access from your own tools and bots. Send the key as a bearer token. Each endpoint requires the matching scope on the key ("View Staff", "View Shifts", "View Sessions").

curl https://evalyn.tacogroup.uk/api/v1/my-group/staff \
  -H "Authorization: Bearer <your-api-key>"

Promoting & demoting

Change a member's rank from outside the dashboard — a Discord bot, an in-game panel, or your own tooling. The change lands in Evalyn, mirrors to your linked Roblox group, DMs the member, and shows up in the audit log and on their profile exactly as if it had been done by hand.

Endpoints

Request body

Naming the acting user

Pass actor_roblox_id or actor_discord_idand the call is checked against that person's own rank: they must hold manage_staff or edit_staff_roles, must outrank the target, and must outrank the rank being granted. Nobody can rank themselves.

It's optional, but a bot that omits it is telling Evalyn “trust the key, not the person” — so a leaked token can do anything the ceiling allows, and the audit log records the key instead of a name. Send it whenever you know who typed the command.

Discord bot

// /promote @user — discord.js
const res = await fetch(
  "https://evalyn.tacogroup.uk/api/v1/my-group/promote",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.EVALYN_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      discord_id: target.id,
      actor_discord_id: interaction.user.id,  // who ran the command
      reason: `via /promote in #${interaction.channel.name}`,
    }),
  }
);

const data = await res.json();

if (!data.ok) {
  // Branch on `code`, never on the error text — the wording may change.
  const friendly = {
    actor_outranked: "You can't promote someone at or above your own rank.",
    at_ceiling: "They're already at the top of the ladder.",
    key_ceiling_exceeded: "That rank is above what this bot is allowed to grant.",
    target_not_member: "They aren't in the group.",
  }[data.code];
  return interaction.reply(friendly ?? data.error);
}

await interaction.reply(
  `${data.member.username}: ${data.from.name} → ${data.to.name}` +
  (data.roblox && !data.roblox.ok ? `\n⚠️ Roblox group not updated: ${data.roblox.error}` : "")
);

In-game (Luau)

Note expected_rank: Roblox HTTP calls time out and get retried, and a retried promote would move someone two rungs. Sending the rank you believe they hold makes the second attempt fail harmlessly with state_mismatch instead.

local HttpService = game:GetService("HttpService")

local EVALYN_KEY = "ev_…"  -- store in a secret, never in client code
local WORKSPACE  = "my-group"

local function promote(targetUserId: number, actorUserId: number, currentRank: number)
	local ok, res = pcall(function()
		return HttpService:RequestAsync({
			Url = "https://evalyn.tacogroup.uk/api/v1/" .. WORKSPACE .. "/promote",
			Method = "POST",
			Headers = {
				["Authorization"] = "Bearer " .. EVALYN_KEY,
				["Content-Type"] = "application/json",
			},
			Body = HttpService:JSONEncode({
				roblox_id = tostring(targetUserId),
				actor_roblox_id = tostring(actorUserId),
				expected_rank = currentRank,   -- makes a retry safe
				reason = "In-game promotion panel",
			}),
		})
	end)

	if not ok then
		return false, "Could not reach Evalyn"
	end

	local body = HttpService:JSONDecode(res.Body)
	if not body.ok then
		return false, body.error
	end

	return true, body.to.name
end

Response

{
  "ok": true,
  "changed": true,
  "member": {
    "user_id": "cm2…",
    "username": "Builderman",
    "display_name": "Builderman",
    "roblox_id": "156"
  },
  "from": { "name": "Trainee",   "rank": 5 },
  "to":   { "name": "Moderator", "rank": 10 },
  "effective_rank": 10,
  "direction": "promotion",
  "actor": { "user_id": "cm1…", "username": "Shedletsky", "rank": 200 },
  "roblox": { "ok": true, "role": "Moderator (rank 10)" }
}

changed: false means they were already in that role — a no-op, not a failure. effective_rank is what permission and rank gates actually compare against. It usually equals to.rank, but a member can hold additional Evalyn roles alongside their group role, and effective rank is the highest of them — so a demotion can succeed on the group and still leave the member above the rank you demoted them to. Check it if that matters to you. roblox is null when no group is linked, and reports ok: false with a reason if the group update failed. Evalyn is the source of truth: a Roblox failure is reported, never rolled back, so a Roblox outage can't block your staff team.

Error codes

Failures return { "ok": false, "code": "…", "error": "…" }. Branch on code— it's stable; the message is not.