docs/core-routes.md

Core Routes

This file lists the current HTTP routes exposed by Core, grouped by access level.

Common conventions

• Authenticated routes use JWT unless noted otherwise.
• Admin routes require role = admin.
• Node-private routes require the x-node-auth-key header and are documented separately in core-private-routes.md.
• The API returns raw JSON objects and arrays, not a wrapper object.

Public routes

Method	Route	Input	Output / Notes
GET	/health	none	{ status: 'ok', timestamp }
GET	/metrics	none	Prometheus text format
POST	/auth/register	RegisterDto	Creates a user account
POST	/auth/login	LoginDto	Returns JWT tokens
POST	/auth/refresh	RefreshTokenDto	Returns new JWT tokens
POST	/auth/telegram	TelegramAuthDto	Telegram OAuth login
GET	/auth/telegram/bot-id	none	{ botId }
GET	/sub/:uuid/info	query string and request IP	Returns SubscriptionInfo JSON
GET	/sub/:uuid	`format=v2ray	clash

/sub/:uuid output

• format=v2ray - plain text, newline-separated URIs
• format=clash - YAML with proxies
• format=singbox - JSON with outbounds
• unknown or missing format falls back to v2ray

Authenticated user routes

Method	Route	Input	Output / Notes
GET	/auth/me	none	Current user without passwordHash
POST	/auth/telegram/link	TelegramAuthDto	Links Telegram to the current account
DELETE	/auth/telegram/unlink	none	Unlinks Telegram from the current account
GET	/me	none	Current user without passwordHash
PATCH	/me/profile	UpdateProfileDto	Updates name, email, or password
GET	/me/stats	none	UserStats
GET	/me/traffic/daily	none	Daily traffic series
GET	/me/traffic/hourly-dist	none	Hour-of-day distribution
GET	/me/traffic	`period=30d	7d
GET	/me/balance	none	{ balance }
GET	/me/balance/transactions	none	User balance transaction history
GET	/me/subscriptions	none	User subscriptions
GET	/me/links	none	All user subscription links
GET	/me/configs	none	Available node/protocol configs for the current user
POST	/me/links	CreateUserLinkDto	Creates a combined link or a per-subscription link
POST	/me/subscriptions	CreateSubscriptionLinkDto	Legacy per-subscription link creation
POST	/me/subscriptions/:id/reset	none	Resets the selected link UUID
PATCH	/me/subscriptions/links/:id	UpdateSubscriptionLinkDto	Renames or reconfigures a link
DELETE	/me/subscriptions/links/:id	none	Deletes a link
PATCH	/me/subscriptions/:id/auto-renew	UpdateAutoRenewDto	Toggles auto-renew for own subscription

Admin routes - users

Method	Route	Input	Output / Notes
GET	/admin/users	page, limit, search, status, isBlocked	Paginated users
GET	/admin/users/:id	none	User detail
GET	/admin/users/:id/stats	none	User stats
PATCH	/admin/users/:id	UpdateUserDto	Updates email, password, role, block flag, name, comment
PATCH	/admin/users/:id/status	UpdateUserStatusDto	Approves, rejects, or restores a user
DELETE	/admin/users/:id	none	Deletes a user

Admin routes - balance

Method	Route	Input	Output / Notes
POST	/admin/users/:id/balance/transactions	CreateBalanceTransactionDto	Creates a deposit, withdrawal, or refund
GET	/admin/users/:id/balance	none	{ balance }
GET	/admin/users/:id/balance/transactions	none	Full admin transaction history
PATCH	/admin/balance/transactions/:id	UpdateBalanceTransactionDto	Edits a balance transaction

Admin routes - tariffs

Method	Route	Input	Output / Notes
GET	/admin/tariffs	none	Tariff list
GET	/admin/tariffs/:id	none	Tariff detail
POST	/admin/tariffs	CreateTariffDto	Creates a tariff
PATCH	/admin/tariffs/:id	UpdateTariffDto	Updates a tariff
DELETE	/admin/tariffs/:id	none	Deletes a tariff

Admin routes - subscriptions

Method	Route	Input	Output / Notes
GET	/admin/subscriptions	page, limit, status, userId, tariffId	Paginated subscriptions
GET	/admin/users/:id/subscriptions	none	Subscriptions for a user
GET	/admin/users/:id/links	none	All links for a user
POST	/admin/subscriptions	CreateSubscriptionDto	Creates a subscription
DELETE	/admin/subscriptions/:id	none	Cancels a subscription
PATCH	/admin/subscriptions/:id/auto-renew	UpdateAutoRenewDto	Toggles auto-renew
POST	/admin/users/:id/links	CreateUserLinkDto	Creates a link for any user
POST	/admin/subscriptions/:id/links	CreateSubscriptionLinkDto	Creates a link for a specific subscription
POST	/admin/subscriptions/links/:id/reset	none	Resets a link UUID
PATCH	/admin/subscriptions/links/:id	UpdateSubscriptionLinkDto	Updates a link
DELETE	/admin/subscriptions/links/:id	none	Deletes a link

Admin routes - nodes

Method	Route	Input	Output / Notes
GET	/admin/nodes	page, limit	Paginated nodes
GET	/admin/nodes/status	none	Computed node status list
GET	/admin/nodes/outbound-options	none	Node/protocol outbound options
GET	/admin/nodes/:id	none	Node detail
POST	/admin/nodes	CreateNodeDto	Creates a node
PATCH	/admin/nodes/:id	UpdateNodeDto	Updates a node
DELETE	/admin/nodes/:id	none	Deletes a node
POST	/admin/nodes/:id/sync	none	Forces a config sync
POST	/admin/nodes/auth-code	none	Generates a one-time node registration code
POST	/admin/nodes/:id/rotate-key	none	Rotates the node auth key
GET	/admin/nodes/:id/protocols	none	Node protocols
POST	/admin/nodes/:id/protocols	CreateProtocolDto	Creates a node protocol
PUT	/admin/nodes/:id/protocols/:protocolId	UpdateProtocolDto	Updates a node protocol
DELETE	/admin/nodes/:id/protocols/:protocolId	none	Deletes a node protocol
GET	/admin/nodes/:id/accesses	none	User access map for the node
POST	/admin/nodes/:nodeId/access/:userId/:protocol	none	Grants protocol access
DELETE	/admin/nodes/:nodeId/access/:userId/:protocol	none	Revokes protocol access
POST	/admin/nodes/:id/install-xray	InstallXrayDto	Installs an xray version and stores the result
POST	/admin/nodes/:id/restart-xray	none	Restarts xray
POST	/admin/nodes/:id/update-geoip	UpdateGeoipDto	Updates stored geoip/geosite URLs and node files
POST	/admin/nodes/:id/crypto/x25519	none	Generates x25519 keys
POST	/admin/nodes/:id/crypto/mldsa65	none	Generates ML-DSA-65 keys
GET	/admin/nodes/xray/versions	none	Cached xray release tags
GET	/admin/nodes/mtproto/versions	none	Cached telemt release tags
PATCH	/admin/nodes/:id/routing-config	UpdateNodeRoutingConfigDto	Updates per-node routing config
POST	/admin/nodes/:id/routing-config/apply-template	ApplyRoutingTemplateDto	Copies a routing template into the node config
DELETE	/admin/nodes/:id/routing-config	none	Clears per-node routing config
PUT	/admin/nodes/:id/nginx/site	multipart form-data	Uploads cert/key/html for a masking site
GET	/admin/nodes/:id/nginx/site	none	Returns nginx masking site status
DELETE	/admin/nodes/:id/nginx/sites/:domain	none	Deletes a masking site
POST	/admin/nodes/:id/install-mtproto	body { version?: string }	Installs telemt and stores the version
POST	/admin/nodes/:id/restart-mtproto	none	Restarts telemt
GET	/admin/nodes/:id/runtime-status	none	Live runtime status from the node
GET	/admin/nodes/:id/outbounds	none	Node outbounds
POST	/admin/nodes/:id/outbounds	CreateNodeOutboundDto	Creates a node outbound
PATCH	/admin/nodes/:id/outbounds/:outboundId	partial CreateNodeOutboundDto	Updates a node outbound
DELETE	/admin/nodes/:id/outbounds/:outboundId	none	Deletes a node outbound

Admin routes - routing rule sets

Method	Route	Input	Output / Notes
GET	/admin/routing-rule-sets	none	All routing rule sets
POST	/admin/routing-rule-sets	CreateRoutingRuleSetDto	Creates a routing rule set
PATCH	/admin/routing-rule-sets/:id	CreateRoutingRuleSetDto	Updates a routing rule set
DELETE	/admin/routing-rule-sets/:id	none	Deletes a routing rule set

Admin routes - external subscriptions

Method	Route	Input	Output / Notes
GET	/admin/external-subscriptions	none	External subscription sources
GET	/admin/external-subscriptions/:id	none	External subscription source detail
POST	/admin/external-subscriptions	CreateExternalSubscriptionDto	Creates a source
POST	/admin/external-subscriptions/test	TestExternalSubscriptionDto	Tests a URL and returns source data
PATCH	/admin/external-subscriptions/:id	UpdateExternalSubscriptionDto	Updates a source
DELETE	/admin/external-subscriptions/:id	none	Deletes a source

Admin routes - logs and usage

Method	Route	Input	Output / Notes
GET	/admin/logs	page, limit, action, userId	Paginated audit logs
GET	/admin/usage	nodeId, userId, from, to	Up to 1000 traffic usage rows

Admin routes - xray helpers

Method	Route	Input	Output / Notes
POST	/admin/xray/parse-link	{ link }	Parses a proxy link into outbound config

DTO summary

Auth

• LoginDto - email, password
• RegisterDto - email, password
• RefreshTokenDto - refreshToken
• TelegramAuthDto - tgAuthResult

Users

• UpdateProfileDto - name?, email?, password?
• UpdateUserDto - email?, password?, role?, isBlocked?, name?, comment?
• UpdateUserStatusDto - status: 'active' | 'pending' | 'rejected'

Balance

• CreateBalanceTransactionDto - amount, type, comment?, createdAt?
• UpdateBalanceTransactionDto - amount?, type?, comment?

Tariffs

• CreateTariffDto
  • name
  • durationMonths: number | null
  • price
  • trafficLimitBytes?
  • isActive?
  • allowedProtocols: VpnProtocol[]
  • allowedNodeIds?
  • externalSubscriptionIds?
  • allowBittorrent?
  • allowAdult?
• UpdateTariffDto - partial CreateTariffDto

Subscriptions

• CreateSubscriptionDto - userId, tariffId, startAt?
• CreateSubscriptionLinkDto - subscriptionId, name?
• CreateUserLinkDto - subscriptionId?, name?, selectedNodeIds?
• UpdateSubscriptionLinkDto - name?, isEnabled?, selectedNodeIds?
• UpdateAutoRenewDto - autoRenew

Nodes

• CreateNodeDto
  • name
  • host
  • port?
  • useSsl?
  • ip?
  • region?
  • metadata?
  • comment?
  • emoji?
  • status?
  • useIpInSubscription?
• UpdateNodeDto - partial CreateNodeDto plus geoipUrl? and geositeUrl?
• CreateProtocolDto - protocol, config?, label?, isEnabled?
• UpdateProtocolDto - config?, label?, isEnabled?
• CreateNodeOutboundDto
  • name
  • tag
  • outboundType? = manual | node
  • config?
  • targetNodeId?
  • targetProtocolId?
• CreateRoutingRuleSetDto
  • name
  • description?
  • domainStrategy?
  • rules?
  • balancers?
  • blockTorrents?
  • blockAds?
  • blockMalware?
  • blockPhishing?
  • blockCryptominers?
  • blockAdult?
• UpdateNodeRoutingConfigDto - same routing fields as above, without name and description
• ApplyRoutingTemplateDto - templateId
• InstallXrayDto - version
• UpdateGeoipDto - geoipUrl?, geositeUrl?

External subscriptions

• CreateExternalSubscriptionDto - name, url, description?
• UpdateExternalSubscriptionDto - partial CreateExternalSubscriptionDto
• TestExternalSubscriptionDto - url

Routing rules

XrayRule fields:

• type (field)
• domainMatcher?
• domain?
• ip?
• port?
• sourcePort?
• localPort?
• network?
• source?
• sourceIP?
• localIP?
• user?
• inboundTag?
• protocol?
• attrs?
• process?
• vlessRoute?
• webhook?
• outboundTag?
• balancerTag?
• ruleTag?

XrayBalancer fields:

• tag
• selector
• strategy?
• fallbackTag?

XrayDomainStrategy values:

• AsIs
• IPIfNonMatch
• IPOnDemand

XrayBalancerStrategy values:

• random
• roundRobin
• leastPing
• leastLoad