API Reference - All Things Linux

The atl.chat stack exposes several internal APIs for server management, IRC services, XMPP user provisioning, and cross-protocol identity resolution. Most APIs are consumed internally by other services in the stack or by the external Portal application — they are not designed for direct end-user access.

API overview

API	Protocol	Port	Consumer	Purpose
UnrealIRCd JSON-RPC	JSON-RPC 2.0	8600	WebPanel, Portal	IRC server management
Atheme HTTP API	JSON-RPC	8081	Portal	IRC services management (NickServ, ChanServ, etc.)
Prosody REST API	REST (HTTP)	5280	Portal	XMPP user account provisioning
Portal Bridge API	REST (HTTP)	—	Bridge	Cross-protocol identity resolution
Fumadocs Search API	REST (HTTP)	3000	Docs UI	Documentation full-text search

UnrealIRCd JSON-RPC

UnrealIRCd 6.x exposes a JSON-RPC 2.0 interface for server management. The WebPanel and Portal use this API to query server state, manage users, and perform administrative actions.

Detail	Value
Endpoint	`https://<IRC_DOMAIN>:8600/api`
Protocol	JSON-RPC 2.0 over HTTPS
Authentication	HTTP Basic (`IRC_UNREAL_RPC_USER` / `IRC_UNREAL_RPC_PASSWORD`)
Internal socket	`/home/unrealircd/unrealircd/data/rpc.socket` (used by healthcheck)

The healthcheck verifies the RPC socket is responsive:

echo '{"jsonrpc":"2.0","method":"rpc.info","params":{},"id":1}' \
  | nc -U /home/unrealircd/unrealircd/data/rpc.socket

Common methods include rpc.info, user.list, channel.list, and server.rehash. See the UnrealIRCd JSON-RPC documentation for the full method reference.

Environment variables

Variable	Description	Default
`IRC_UNREAL_JSONRPC_URL`	Full RPC endpoint URL	`https://irc.atl.chat:8600/api`
`IRC_UNREAL_RPC_USER`	RPC username (matches `WEBPANEL_RPC_USER`)	`adminpanel`
`IRC_UNREAL_RPC_PASSWORD`	RPC password (matches `WEBPANEL_RPC_PASSWORD`)	`change_me_webpanel_password`

Warning: Change IRC_UNREAL_RPC_PASSWORD before production deployment. This credential grants full administrative access to the IRC server.

Atheme HTTP API

Atheme IRC services expose an HTTP JSON-RPC interface for programmatic access to NickServ, ChanServ, OperServ, and other service bots. The Portal uses this API to manage IRC registrations and query account information.

Detail	Value
Endpoint	`http://atl-irc-server:8081/jsonrpc`
Protocol	JSON-RPC over HTTP
Authentication	Atheme credentials (configured in Atheme’s `httpd` block)

Atheme shares the network namespace with UnrealIRCd (network_mode: service:atl-irc-server), so port 8081 is exposed through the IRC server container.

Environment variables

Variable	Description	Default
`IRC_ATHEME_JSONRPC_URL`	Atheme JSON-RPC endpoint URL	`http://atl-irc-server:8081/jsonrpc`

Prosody REST API

Prosody exposes a REST API via mod_http_admin_api for XMPP user account management. The Portal uses this API to provision and deprovision XMPP accounts. Self-registration is disabled — all user creation flows through this API.

Detail	Value
Base URL	`http://atl-xmpp-server:5280`
Protocol	REST over HTTP
Authentication	Bearer token (via `mod_tokenauth`) — primary for Portal. OAuth2 Bearer (via `mod_http_oauth2`) or HTTP Basic also supported.
Module	`mod_http_admin_api` (loaded per-VirtualHost, not globally)

Portal integration: Use PROSODY_REST_TOKEN (Bearer) for Portal. Generate a token with just prosody-token or prosodyctl shell (see Prosody configuration docs). Legacy PROSODY_REST_USERNAME / PROSODY_REST_PASSWORD (HTTP Basic) are deprecated for Portal — Prosody 13+ with mod_http_admin_api uses Bearer auth via mod_tokenauth.

Environment variables (Portal)

Variable	Description	Default
`PROSODY_REST_URL`	Prosody REST API base URL	`http://atl-xmpp-server:5280`
`PROSODY_REST_TOKEN`	Bearer token for `mod_http_admin_api` (primary for Portal)	—
`PROSODY_REST_USERNAME`	REST admin username (JID) — legacy, HTTP Basic	`admin@atl.chat`
`PROSODY_REST_PASSWORD`	REST admin password — legacy, HTTP Basic	`change_me_prosody_rest_password`

Warning: PROSODY_REST_TOKEN (or PROSODY_REST_PASSWORD if using legacy Basic auth) grants admin-level access to XMPP user management. Change from defaults before production deployment.

Portal Bridge API

The bridge optionally integrates with the Portal application for unified user identity across protocols. The Portal is a separate Next.js project and is not part of this monorepo. When BRIDGE_PORTAL_BASE_URL is set, the bridge creates a PortalClient and IdentityResolver to map users between Discord, IRC, and XMPP.

Identity endpoint

The bridge calls a single Portal endpoint to resolve cross-protocol identities:

GET {BRIDGE_PORTAL_BASE_URL}/api/bridge/identity

Authentication uses a Bearer token (BRIDGE_PORTAL_TOKEN) in the Authorization header.

Query parameters

Look up a user identity by providing one of the following query parameters:

Parameter	Type	Description
`discordId`	string	Discord user ID
`ircNick`	string	IRC nickname
`ircServer`	string	IRC server hostname (optional, used with `ircNick`)
`xmppJid`	string	XMPP JID

Response

The endpoint returns a JSON object with the user’s linked identities:

{
  "ok": true,
  "identity": {
    "user_id": "portal-user-id",
    "discord_id": "123456789",
    "irc_nick": "username",
    "xmpp_jid": "username@atl.chat"
  }
}

Returns 404 when no matching identity is found. The bridge’s IdentityResolver caches results in a TTL cache (default: 1 hour, max 1024 entries) to reduce API calls.

Identity resolution flow

The bridge uses the IdentityResolver to translate user identities when relaying messages:

A message arrives on one protocol (e.g., Discord)
The resolver checks its TTL cache for a cached identity
On cache miss, it calls GET /api/bridge/identity?discordId=<id>
The Portal returns the linked IRC nick and/or XMPP JID
The bridge uses the resolved identity for puppet nicks on the target protocol

When BRIDGE_PORTAL_BASE_URL is not set, identity resolution is disabled and the bridge falls back to dev puppet nicks or generic relay formatting.

Environment variables

Variable	Description	Default
`BRIDGE_PORTAL_BASE_URL`	Portal API base URL	`https://portal.atl.tools`
`BRIDGE_PORTAL_TOKEN`	Bearer token for Portal API	`change_me_bridge_portal_token`

Warning: Change BRIDGE_PORTAL_TOKEN before production deployment.

Retry behaviour

The PortalClient uses exponential backoff retries (up to 5 attempts, 2–30 second delays) for transient HTTP errors including connection timeouts, read/write errors, and HTTP status errors.

Fumadocs Search API

The docs site exposes an Orama search endpoint used by the built-in search UI:

GET /api/search?query=<term>

This is an internal endpoint powering the documentation search bar. It is not intended for external consumption and its schema may change between releases.

Future APIs

The following APIs are planned or under consideration:

Bridge metrics endpoint — expose relay statistics (message counts, latency, error rates) for monitoring integration
Bridge admin API — runtime configuration changes (reload config, pause/resume relays) without container restart
Portal webhook receiver — allow the Portal to push identity updates to the bridge instead of polling

These APIs will be documented here as they are implemented. Track progress in the atl.chat GitHub repository.

Environment Variables — full variable reference including all API credentials
Ports Reference — complete port registry for all services
Bridge Configuration — bridge setup and Portal integration
WebPanel Configuration — WebPanel RPC connection setup
Security — credential rotation and secret management

​API overview

​UnrealIRCd JSON-RPC

​Environment variables

​Atheme HTTP API

​Environment variables

​Prosody REST API

​Environment variables (Portal)

​Portal Bridge API

​Identity endpoint

​Query parameters

​Response

​Identity resolution flow

​Environment variables

​Retry behaviour

​Fumadocs Search API

​Future APIs

​Related pages

API overview

UnrealIRCd JSON-RPC

Environment variables

Atheme HTTP API

Environment variables

Prosody REST API

Environment variables (Portal)

Portal Bridge API

Identity endpoint

Query parameters

Response

Identity resolution flow

Environment variables

Retry behaviour

Fumadocs Search API

Future APIs

Related pages