API overview#

koja-mdt exposes four integration surfaces:

The integrations page explains the editable/ bridges for jails, fines, impounds and frameworks, and the examples page has complete recipes.

Getting started#

1. Start order#

   Start your resource after koja-mdt (and its dependencies oxmysql and koja-lib).
   server.cfg

   ensure oxmysql
   ensure koja-lib
   ensure koja-mdt
   ensure my-robberies

2. Call an export#

   server.lua

   local mdt = exports['koja-mdt']
   local medics = mdt:CountOnDuty({ type = 'ems' })

3. Handle errors#

   Most write exports return result, errorCode. Always check the first value.
   server.lua

   local warrant, err = exports['koja-mdt']:CreateWarrant({ type = 'arrest', name = 'John Doe', reason = 'Armed robbery' })
   if not warrant then
       print('warrant failed: ' .. tostring(err))
   end

Conventions#

Sources and identifiers#

Acting identity#

Write exports run through the same internal action handlers as the tablet (Api.Invoke), so permissions, audit logs, hooks, Discord webhooks and live sync behave exactly as if an officer did it. Who the action runs as is controlled by an options table, passed either inside the input table (CreateIncident(data)) or as the last argument (opts):

Without officer, the action runs as System: a virtual session with every permission and the command rank. Server resources are trusted, so System bypasses the permission checks but never the input validation, the hooks or the state rules (for example you still cannot pay a void citation).

Permissions#

Permission names are listed in shared/permissions.lua and returned by GetPermissionList(). Ranks map to permission sets per department.

if exports['koja-mdt']:HasPermission(source, 'warrants.approve') then
    -- the player can approve warrants in the MDT
end

Error codes#

Errors are short machine-readable strings. The ones you will meet most often:

Domain-specific codes (plate_required, no_violations, bed_taken, already_impounded, bill_too_high, cooldown, …) are listed next to each export.

Common shapes#

These shapes are returned by many exports. Fields can be nil when the value is unknown.

Officer#

{
    source = 4, identifier = 'ABC12345', name = 'John Doe', callsign = '1-ADAM-12', badge = '1042',
    department = 'lspd', rank = 'officer', gradeLabel = 'Officer II',
    status = 'available', onDuty = true, call = 12, image = 'https://...',
}

Dispatch call#

{
    id = 12, code = '10-90', title = 'Bank alarm', message = 'Fleeca Great Ocean', street = 'Great Ocean Hwy',
    coords = { x = 0.0, y = 0.0, z = 0.0 }, priority = 1, status = 'active',
    caller = { name = 'Alarm company', phone = nil },
    units = { { source = 4, callsign = '1-ADAM-12', name = 'John Doe', department = 'lspd' } },
    notes = { { by = '1-ADAM-12 John Doe', text = 'Suspects left north', at = 1730000000000 } },
    blip = { sprite = 161, color = 1, scale = 1.2 }, createdAt = 1730000000000,
}

Timestamps#

Database timestamps come back the way oxmysql returns them (usually a number of milliseconds). Live dispatch data (createdAt, note at) is always milliseconds since epoch.

Generic action bridge#

Every tablet action can also be called directly. Use the named exports when one exists; Invoke is the escape hatch for anything else.

local result, err = exports['koja-mdt']:Invoke('divisions:list', {}, { department = 'lspd' })

See Invoke and GetApiActions in the server exports for details.