Logbook - BloxCord V3

Locked & classified visibility

Two fields control who can see a logbook entry:

locked — an array of role ids allowed to view/unlock the entry.
classified — an array of role ids allowed to view a classified entry.

An empty array ({}) means no restriction. You provide these role ids when creating an entry, and getLogbookEntries returns them back as arrays.

Legacy entries created before role-scoped visibility stored a plain boolean. When such an entry is read, its locked / classified value is returned as the single-element array { "legacy_role" } instead of a boolean.

Locked & classified entries are an Enterprise-only feature. Calls that reference them from lower plans will silently drop the restriction.

createLogbookEntry

Creates a new logbook entry (warning, ban, mute, rank lock, etc.) for a user. Every side effect the dashboard would run also runs here: rank changes on suspensions and demotions, optional machine bans, Discord DMs to the target, Actions engine emits, and an audit trail entry.

local result = BloxCord:Invoke("createLogbookEntry", actor, target, opts)

Parameters

Player | table | number

required

Who is issuing the entry. See the actor object.

Player | number | string

required

The user receiving the entry. Accepts a Player instance or a raw UserId.

table

required

Entry options.

Show opts fields

string

required

The logbook entry type. One of suspension, demotion, promotion, tban, mute, toolban, rlock, verbalwarning, warning, modcallban, serverban, kick, comment, shrnote.

string

Human-readable reason for the entry.

number

Unix timestamp (ms) at which the entry expires. Omit for a permanent entry.

boolean

default:"false"

Whether this is a machine ban. (Open-Cloud User Restrictions API - Alt Block)

string[]

Array of role ids permitted to view/unlock the entry. Omit or pass an empty array for no restriction.

string[]

Array of role ids permitted to view the entry when classified. Omit or pass an empty array for no restriction.

table

Optional rule references associated with the entry.

Returns

table | nil

The created entry payload from the dashboard on success, or nil if the request was rejected or the backend was unreachable.

Example

local BloxCord = game:WaitForChild("BloxCord")

BloxCord:Invoke("createLogbookEntry", moderator, offender, {
    type = "warning",
    reason = "Spamming in chat",
    expiry = os.time() * 1000 + (7 * 24 * 60 * 60 * 1000), -- 7 days
    locked = { "role_235235235seniorstaff", "role_hr" }, -- only these roles can view/unlock. Note that these are role IDs, not role names.
})

getLogbookEntries

Fetches a user’s logbook entries, optionally filtered by type and active state.

local entries = BloxCord:Invoke("getLogbookEntries", userId, filters)

Parameters

number | string

required

The UserId whose entries to fetch.

table

Optional filters.

Show filters fields

string

Only return entries of this type (e.g. "tban", "rlock").

boolean

When true, only return entries that are not reverted and not expired.

Returns

object[]

An array of logbook entries. Empty if none match or the request failed.

Show entry fields

string

Unique entry id.

string

Entry type.

string

Reason text.

number

Target’s rank at time of entry.

string

Target’s role at time of entry.

number

New rank (for rank changes).

string

New role (for rank changes).

number

Duration, if applicable.

number

Creation timestamp (ms).

number | null

Expiry timestamp (ms), or null if permanent.

boolean

Whether the entry was reverted.

string[]

Array of role ids allowed to view/unlock the entry. Empty if unrestricted. Legacy entries return { "legacy_role" }.

string[]

Array of role ids allowed to view the classified entry. Empty if unrestricted. Legacy entries return { "legacy_role" }.

object

The actor who created the entry.

Example

local BloxCord = game:WaitForChild("BloxCord")

local activeBans = BloxCord:Invoke("getLogbookEntries", player.UserId, {
    type = "ban",
    active = true,
})

if #activeBans > 0 then
    local ban = activeBans[1]
    if #ban.locked > 0 then
        print("Entry is locked to roles:", table.concat(ban.locked, ", "))
    end
    player:Kick("You are banned: " .. ban.reason)
end

checkranklock

Convenience check for whether a user currently has an active rank lock (rlock) entry. Equivalent to calling getLogbookEntries with type = "rlock" and active = true and testing for results, just shorter and faster to write.

local locked = BloxCord:Invoke("checkranklock", userId)

Parameters

number | string

required

The UserId to check.

Returns

boolean

true if the user has at least one active rank lock, otherwise false.

Example

local BloxCord = game:WaitForChild("BloxCord")

if BloxCord:Invoke("checkranklock", targetUserId) then
    warn("Cannot rank this user, they are rank-locked.")
    return
end

Wire checkranklock into any in-game ranking UI or admin command to prevent staff from accidentally overriding an active rank lock set from the dashboard.

​Locked & classified visibility

​createLogbookEntry

​Parameters

​Returns

​Example

​getLogbookEntries

​Parameters

​Returns

​Example

​checkranklock

​Parameters

​Returns

​Example

Locked & classified visibility

createLogbookEntry

Parameters

Returns

Example

getLogbookEntries

Parameters

Returns

Example

checkranklock

Parameters

Returns

Example