oRPC API Endpoints¶

The MAGK platform exposes a typed API built with oRPC and Zod validation. All endpoints are mounted at /api/* and return responses in the standard MAGK envelope format.

Response Envelope¶

Every oRPC endpoint returns a consistent JSON envelope:

// Success response
interface ApiResponse<T> {
  success: true
  data: T
  message?: string
  timestamp: string  // ISO 8601
}

// Error response
interface ApiErrorResponse {
  success: false
  error: {
    code: string                      // e.g. "VALIDATION_INVALID_EMAIL"
    message: string                   // Human-readable description
    details?: Record<string, string[]> // Field-level validation errors
  }
  timestamp: string
}

Example success response:

{
  "success": true,
  "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Operation Nightfall" },
  "message": "Event created",
  "timestamp": "2025-01-15T14:30:00.000Z"
}

Authentication¶

Endpoints use session-based authentication via Better Auth. Three access levels exist:

Level	Description	Header
Public	No authentication required	—
Protected	Valid session required	`Cookie: session=<token>`
Admin	Valid session + `admin` role	`Cookie: session=<token>`

Unauthenticated requests to protected endpoints return:

{ "success": false, "error": { "code": "UNAUTHORIZED", "message": "Authentication required" }, "timestamp": "..." }

Paginated Responses¶

List endpoints that support pagination extend the standard envelope:

interface PaginatedResponse<T> extends ApiResponse<T[]> {
  pagination: {
    page: number
    pageSize: number
    total: number
    totalPages: number
  }
}

Auth¶

Procedure	Method	Auth	Description
`auth.resolveLogin`	POST	Public	Resolve a username or email to an email address for login. Returns `{ email }`. Rate-limited to 10 requests/minute per IP.

Events¶

Procedure	Method	Auth	Description
`events.list`	POST	Protected	List events, optionally filtered by status (`draft`, `registration_open`, `registration_closed`, `staging`, `active`, `paused`, `completed`, `cancelled`).
`events.get`	POST	Protected	Get a single event by UUID.
`events.create`	POST	Admin	Create a new event with name, dates, location, and configuration.
`events.update`	POST	Admin	Update event fields by UUID.
`events.delete`	POST	Admin	Delete an event by UUID. Cascades to related registrations and missions.
`events.transitionStatus`	POST	Organizer	Transition event status. Requires `id`, `currentStatus`, `newStatus`. Optional `force: true` bypasses state machine validation (admin only).

Users¶

Procedure	Method	Auth	Description
`users.list`	POST	Admin	List all platform users with role and status.
`users.get`	POST	Admin	Get a single user by UUID.
`users.create`	POST	Admin	Create a new user with role assignment.
`users.update`	POST	Admin	Update user fields (role, active status, profile).
`users.delete`	POST	Admin	Deactivate or delete a user by UUID.

Groups¶

Procedure	Method	Auth	Description
`groups.list`	POST	Protected	List groups (platoons, squads) for an event.
`groups.get`	POST	Protected	Get a single group by UUID with roster.
`groups.create`	POST	Admin	Create a group (platoon or squad) within an event.
`groups.update`	POST	Admin	Update group name, type, or parent assignment.
`groups.delete`	POST	Admin	Delete a group by UUID.

Nodes¶

Procedure	Method	Auth	Description
`nodes.list`	POST	Protected	List MAGK Nodes, optionally filtered by status.
`nodes.get`	POST	Protected	Get a single node by UUID.
`nodes.register`	POST	Admin	Register a new MAGK Node device.
`nodes.update`	POST	Admin	Update node fields (status, config, location, assignment).
`nodes.configure`	POST	Admin	Push a configuration object to a node. Sets `configurationStatus` to `sent`.
`nodes.delete`	POST	Admin	Delete a node by UUID.

Missions¶

Procedure	Method	Auth	Description
`missions.list`	POST	Protected	List missions for an event.
`missions.get`	POST	Protected	Get a single mission by UUID with objectives.
`missions.create`	POST	Admin	Create a mission with name, description, and event assignment.
`missions.update`	POST	Admin	Update mission fields.
`missions.delete`	POST	Admin	Delete a mission by UUID.

Objectives¶

Procedure	Method	Auth	Description
`objectives.list`	POST	Protected	List objectives for a mission.
`objectives.get`	POST	Protected	Get a single objective by UUID.
`objectives.create`	POST	Admin	Create an objective with location, scoring rules, and mission assignment.
`objectives.update`	POST	Admin	Update objective fields.
`objectives.delete`	POST	Admin	Delete an objective by UUID.

Scoring¶

Procedure	Method	Auth	Description
`gameModes.list`	POST	Protected	List available game modes.
`gameModes.get`	POST	Protected	Get a single game mode by UUID.
`gameModes.create`	POST	Admin	Create a game mode with scoring rules.
`gameModes.update`	POST	Admin	Update game mode configuration.
`gameModes.delete`	POST	Admin	Delete a game mode by UUID.
`playerRoles.list`	POST	Protected	List player roles.
`playerRoles.create`	POST	Admin	Create a player role.
`playerRoles.update`	POST	Admin	Update a player role.
`playerRoles.delete`	POST	Admin	Delete a player role.

Registrations¶

Procedure	Method	Auth	Description
`registrations.list`	POST	Protected	List registrations for an event.
`registrations.get`	POST	Protected	Get a single registration by UUID.
`registrations.create`	POST	Public	Register a player for an event (public registration or kiosk). Rate-limited.
`registrations.update`	POST	Admin	Update registration status or assignment.
`registrations.delete`	POST	Admin	Delete a registration by UUID.

Certificates¶

Procedure	Method	Auth	Description
`certificates.list`	POST	Admin	List issued TAK client certificates.
`certificates.create`	POST	Admin	Issue a new client certificate.
`certificates.revoke`	POST	Admin	Revoke a certificate by UUID.
`certificates.delete`	POST	Admin	Delete a certificate record.

Data Packages¶

Procedure	Method	Auth	Description
`dataPackages.list`	POST	Protected	List data packages.
`dataPackages.get`	POST	Protected	Get a single data package by UUID.
`dataPackages.create`	POST	Admin	Upload and create a data package.
`dataPackages.delete`	POST	Admin	Delete a data package by UUID.

Federation¶

Procedure	Method	Auth	Description
`federation.list`	POST	Admin	List federation connections.
`federation.get`	POST	Admin	Get a single federation connection.
`federation.create`	POST	Admin	Create a federation connection to a remote TAK server.
`federation.update`	POST	Admin	Update federation connection settings.
`federation.delete`	POST	Admin	Delete a federation connection.

Media¶

Procedure	Method	Auth	Description
`media.list`	POST	Protected	List media streams and recordings.
`media.get`	POST	Protected	Get a single media item by UUID.
`media.create`	POST	Admin	Create a media stream entry.
`media.update`	POST	Admin	Update media metadata.
`media.delete`	POST	Admin	Delete a media item.

Overlays¶

Procedure	Method	Auth	Description
`overlays.list`	POST	Protected	List map overlays for an event.
`overlays.get`	POST	Protected	Get a single overlay by UUID.
`overlays.create`	POST	Admin	Create a map overlay with GeoJSON geometry.
`overlays.update`	POST	Admin	Update overlay properties or geometry.
`overlays.delete`	POST	Admin	Delete an overlay by UUID.

Audit Logs¶

Procedure	Method	Auth	Description
`auditLogs.list`	POST	Admin	List audit log entries with filtering by action, user, entity, and date range.
`auditLogs.get`	POST	Admin	Get a single audit log entry by UUID.

Infrastructure¶

Procedure	Method	Auth	Description
`ecsLogs.list`	POST	Admin	List ECS-formatted system log entries.
`ecsLogs.get`	POST	Admin	Get a single log entry by UUID.

Settings¶

Procedure	Method	Auth	Description
`settings.list`	POST	Admin	List all platform settings.
`settings.get`	POST	Admin	Get a setting by key.
`settings.update`	POST	Admin	Update a setting value.

Additional Routers¶

The following routers provide specialized functionality:

Router	Auth	Description
`roster`	Admin	Roster management — assign players to squads, finalize rosters (provisions TAK groups and Mumble channels).
`mumble`	Admin	Mumble voice server administration — channel CRUD, ACL management, user management.
`workflows`	Admin	Workflow canvas management — create and update event workflow definitions.
`deviceProfiles`	Admin	Device profile management for TAK client configuration.
`wifiNetworks`	Admin	Wi-Fi network configuration for node provisioning.
`qrCodes`	Admin	QR code generation for registration and kiosk enrollment.
`nodeConfig`	Admin	Node configuration template management.
`playerPortal`	Protected	Player-facing portal — view assigned events, team info, and scores.
`delegations`	Admin	Delegation management for organizer permissions.
`drawings`	Protected	Map drawing/annotation management.
`trackHistory`	Protected	Historical CoT track data queries.
`chat`	Protected	Chat message management for event chatrooms.

Mumble Voice Communications¶

Procedure	Method	Auth	Description
`mumble.status`	POST	Admin	Get Mumble server connection status (connected, disconnected, disabled).
`mumble.serverTree`	POST	Admin	Get the full channel/user tree including connected users and their status.
`mumble.serverCreateChannel`	POST	Admin	Create a channel under a specified parent. Input: `{ parentId, name }`.
`mumble.serverDeleteChannel`	POST	Admin	Delete a channel by ID. Cascades to sub-channels; connected users moved to parent.
`mumble.serverRenameChannel`	POST	Admin	Rename a channel. Input: `{ channelId, name }`.
`mumble.serverSetChannelACL`	POST	Admin	Set ACL rules for a channel. Input: `{ channelId, acls: [{ group, allow, deny }] }`.
`mumble.serverGetChannelACL`	POST	Admin	Get current ACL rules for a channel. Returns group entries with permission flags.
`mumble.allConnectedUsers`	POST	Admin	List all currently connected users with session ID, channel, and mute/deaf status.
`mumble.serverKickUser`	POST	Admin	Kick a user from the server by session ID. Input: `{ sessionId, reason? }`.
`mumble.internalMumbleGroups`	POST	None	Internal membership lookup for the Ice authenticator. No auth required (internal network only). Returns group names for a given username.