docs/core-private-routes.md

Core Private Node Routes

These routes are consumed only by the node agent and require the x-node-auth-key header.

Authentication

• POST /node/register is the only public route in this group.
• All other routes require a valid node auth key.
• The auth key is issued by Core during registration and persisted on the node side.

Route table

Method	Route	Input	Output / Notes
POST	/node/register	RegisterNodeDto	Returns { authKey, nodeId }
POST	/node/heartbeat	NodeHeartbeatDto	Returns { ok: true, needSync }
POST	/node/usage	NodeUsageDto	Returns { ok: true }
POST	/node/outbound-usage	NodeOutboundUsageDto	Returns { ok: true }
POST	/node/session-events	SessionEventsDto	Returns { ok: true }
GET	/node/config/latest	none	Returns NodeConfig
POST	/node/config/applied	NodeConfigAppliedDto	Returns { ok: true }
POST	/node/error	NodeErrorDto	Returns { ok: true }

Request payloads

RegisterNodeDto

• code: string
• name: string
• host: string
• ip: string
• region: string

NodeHeartbeatDto

• ip?: string
• revision?: number

The node sends its current revision in heartbeats. Core uses it to decide whether a sync is needed.

NodeUsageDto

• entries: UsageEntryDto[]

UsageEntryDto fields:

• userId: number
• subscriptionId?: number | null
• nodeProtocolId: number
• bytesUp: number
• bytesDown: number
• recordedAt: string

NodeOutboundUsageDto

• items: OutboundUsageItem[]

OutboundUsageItem fields:

• tag: string
• bytesUp: number
• bytesDown: number

SessionEventsDto

• events: SessionEventEntryDto[]

SessionEventEntryDto fields:

• userId: number
• protocol: VpnProtocol
• eventType: SessionEventType
• occurredAt: string
• ipAddress?: string

NodeConfigAppliedDto

• revision: number

NodeErrorDto

• message: string
• code?: string
• details?: Record<string, unknown>

NodeConfig

The config returned by GET /node/config/latest has this structure:

{
  revision: number
  clientMap: Record<string, { userId: number; subscriptionId: number | null }>
  services: {
    xray?: XrayServiceConfig
    mtproto?: MtProtoServiceConfig
  }
}

Important notes:

• clientMap maps subscription link UUIDs to the user and subscription used for traffic attribution.
• services.xray contains the Xray inbounds, routing, and outbounds for the node.
• services.mtproto contains MTProto inbounds for telemt.
• the node stores the current revision and client map locally after a successful apply

Route semantics

• POST /node/heartbeat updates lastSeenAt and can request a sync when the node revision is behind.
• POST /node/usage stores per-minute usage rows and increments subscription traffic counters.
• POST /node/outbound-usage increments node_outbounds.traffic_bytes_up/down.
• POST /node/session-events stores online/offline events in session_events.
• POST /node/config/applied marks the node sync status as synced.
• POST /node/error marks the node as error and the sync status as failed.