API Documentation

Authenticate with username and password to receive a JWT token.

Request Body

Example

curl -X POST https://portal.example.com/api/token \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "pass"}'

Response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2024-01-15T12:00:00Z",
  "user": {
    "id": 1,
    "username": "user",
    "is_admin": false
  }
}

Request Body

Response

{
  "id": 1,
  "name": "My Integration",
  "api_key": "portal_abc123...",
  "key_prefix": "portal_abc",
  "scopes": "*",
  "expires_at": null
}

Returns all API keys for the authenticated user. Keys are shown with prefix only (not full key).

Revokes the API key. The key will no longer work for authentication but remains in your key list.

Permanently delete an API key from your account.

Returns all active JWT tokens for the authenticated user.

Request Body

Register a new account using an invite code. Rate limited to 1 account per IP per 24 hours.

Request Body

Response

{
  "id": 5,
  "username": "newuser",
  "message": "Registration successful"
}

Returns public metrics visible to all authenticated users, including live stream counts and online user counts.

Response

{
  "live_streams": 3,
  "online_users": 12
}

Fields

• live_streams - Number of currently live public streams
• online_users - Number of unique users currently in chat

Returns all services the authenticated user has access to based on their scopes.

Response

{
  "services": [
    {
      "id": 1,
      "name": "Home Server",
      "plugin": "ssh",
      "path": "/homeserver",
      "icon": "terminal",
      "category": "Servers",
      "enabled": true
    }
  ]
}

Returns detailed information about a specific service.

Checks if the backend service is reachable and responding.

Response

{
  "healthy": true,
  "latency_ms": 45
}

Returns available connection types with their plugin schemas for form generation.

Response

{
  "types": {
    "ssh": {
      "name": "SSH Terminal",
      "icon": "terminal",
      "default_port": 22,
      "plugin": "ssh",
      "config_schema": {...}
    },
    "vnc": {...},
    "rdp": {...}
  }
}

Returns all connections for the authenticated user.

Request Body

Example

curl -X POST https://portal.example.com/api/connections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Home Server",
    "type": "ssh",
    "host": "192.168.1.100",
    "port": 22,
    "config": {
      "username": "admin",
      "auth_method": "password"
    }
  }'

Returns details for a specific connection. Sensitive config fields (passwords, private keys) are redacted and replaced with has_<field> boolean flags.

Update a connection. Config fields are merged server-side with the existing config — sensitive fields not included in the request are preserved from the encrypted database record.

Request Body

Permanently delete a connection.

Toggle whether a connection is pinned. Pinned connections sort to the top of the connections list for quick access.

Response

{
  "is_pinned": true
}

Returns connection details and WebSocket URL needed to establish a connection. The dashboard uses this to open the appropriate viewer window.

Response

{
  "connection": {
    "id": 1,
    "type": "ssh",
    "name": "My Server",
    "host": "10.0.0.5",
    "port": 22,
    "config": {}
  },
  "ssh_public_key": "ssh-ed25519 AAAA... (if SSH key is set)",
  "websocket_url": "/ws/user-connection/1"
}

Connection Type Routing

All viewer pages connect via wss://portal/ws/user-connection/{id} which routes through the appropriate plugin based on the connection type.

Returns all streams owned by the authenticated user.

Response

{
  "streams": [
    {
      "id": 1,
      "title": "My Live Stream",
      "stream_key": "sk_abc123...",
      "is_live": 0,  // 0=offline, 1=live, 2=encoding
      "is_public": true,
      "rtmp_enabled": false,
      "viewer_count": 0,
      "chat_channel_id": 5,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ]
}

Creates a new stream with a unique stream key. An associated chat channel is automatically created.

Request Body

Response

{
  "id": 1,
  "title": "My Stream",
  "stream_key": "sk_abc123def456...",
  "rtmp_enabled": false,
  "chat_channel_id": 5,
  "playback_urls": {
    "hls": "https://portal.example.com/api/stream/sk_abc123/hls/index.m3u8",
    "webrtc": "https://portal.example.com/api/stream/sk_abc123/webrtc/whep"
  }
}

Returns all public streams (live, encoding, and offline). Used by the community streams page. The is_live field is an integer: 0=offline, 1=live, 2=encoding (VOD finalization in progress).

Returns all public streams that are currently live. Includes viewer counts and playback URLs.

Returns detailed information about a specific stream including playback URLs.

Update title, description, or visibility of your stream.

Request Body

Generate a new stream key, invalidating the old one. Use this if your key is compromised.

Generate a temporary token for publishing via plain RTMP (unencrypted). The stream must have rtmp_enabled: true and the server must have RTMP_PLAIN_ENABLED set globally.

Prerequisites

• Stream must have rtmp_enabled set to true
• Global RTMP_PLAIN_ENABLED must be enabled by the server administrator
• Authenticated as the stream owner (Bearer token)

Response

{
  "token": "rtmp_abc123...",
  "expires_in": 900,
  "rtmp_url": "rtmp://stream.example.com:1935/live"
}

Internally, the token doubles as the MediaMTX publish path. Portal maps it back to the stream automatically, so all stream features (HLS playback, dynamic thumbnails, VOD recording) work seamlessly with plain RTMP.

Permanently delete a stream and its associated chat channel.

Upload a custom thumbnail image (owner only). Multipart form data with field thumbnail. Max 2MB, JPEG/PNG.

Remove a custom thumbnail for a stream (owner only). The stream will revert to using a dynamic thumbnail when live.

Returns a dynamic JPEG thumbnail captured from a live stream via ffmpeg. Cached for 15 seconds. Returns static thumbnail (or 404) if stream is offline or encoding. Accepts live_xxx or pub_xxx key.

List users banned from this stream's chat (owner only).

Request Body

Remove a ban, allowing the user to chat again (owner only).

Returns the list of supported relay platforms with their default RTMP ingest URLs.

{
  "platforms": [
    { "id": "twitch", "name": "Twitch", "default_url": "rtmp://live.twitch.tv/app" },
    { "id": "youtube", "name": "YouTube", "default_url": "rtmp://a.rtmp.youtube.com/live2" },
    { "id": "kick", "name": "Kick", "default_url": "rtmps://fa723fc1b171.global-contribute.live-video.net/app" },
    { "id": "portal", "name": "Portal", "default_url": "" },
    { "id": "custom", "name": "Custom", "default_url": "" }
  ]
}

Returns all relay destinations configured for this stream (owner only). Stream keys are never returned; a has_stream_key boolean indicates whether one is set.

Request Body

Update a relay destination's name, URL, stream key, or enabled state (owner only). All fields are optional; only provided fields are updated.

Remove a relay destination (owner only). If the relay is currently active, it will be stopped.

Returns the user's SFTP storage configuration. Passwords and private keys are redacted.

Response

{
  "storage": {
    "host": "storage.example.com",
    "port": 22,
    "username": "user",
    "auth_method": "password",
    "remote_path": "/home/user/vods",
    "has_password": true,
    "has_key": false
  }
}

Request Body

Removes the SFTP storage configuration. Does not delete any remote files.

Tests the SFTP connection with the provided credentials and reports how many MKV files were found.

Recursively lists MKV files in the user's remote storage directory. Files are organized by recording session: StreamName/YYYY-MM-DD_HH-MM-SS/chunk_NNN.mkv. Returns 404 if no storage is configured.

Query Parameters

Response

{
  "files": [
    {
      "name": "StreamName/2026-02-08_04-24-49/chunk_000.mkv",
      "size": 233436982,
      "modified": 1770525031
    }
  ],
  "path": "/home/user/vods"
}

Streams the specified MKV file from remote storage. Only .mkv files are allowed. Supports subdirectory paths. Path traversal is blocked.

Downloads multiple VOD files as a single zip archive streamed from SFTP. Maximum 500 files per request. All paths must end in .mkv.

Request Body

{
  "files": [
    "StreamName/2026-02-08_04-24-49/chunk_000.mkv",
    "StreamName/2026-02-08_04-24-49/chunk_001.mkv"
  ]
}

Response

Binary zip stream with Content-Disposition: attachment header.

Deletes the specified MKV file from remote storage. Only .mkv files can be deleted. Supports subdirectory paths.

Returns information about the authenticated user.

Response

{
  "id": 1,
  "username": "myuser",
  "is_admin": false,
  "scopes": "access:*",
  "created_at": "2024-01-01T00:00:00Z",
  "totp_enabled": true
}

Request Body

Request Body

Request Body

Request Body

Toggle anonymous mode in chat. Messages sent while anonymous remain anonymous in history.

Request Body

Request Body

Response

{
  "id": 1,
  "name": "my-key",
  "public_key": "ssh-ed25519 AAAA...",
  "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...",
  "fingerprint": "SHA256:..."
}

Returns all SSH keys for the authenticated user (public keys only).

Returns details for a specific SSH key (public key only).

Permanently delete an SSH key pair.

Returns all your public keys in authorized_keys format for adding to remote servers.

Response

{
  "enabled": false,
  "backup_codes_remaining": 0
}

Generates a TOTP secret and provisioning URI for authenticator apps.

Response

{
  "secret": "JBSWY3DPEHPK3PXP",
  "provisioning_uri": "otpauth://totp/Portal:user?secret=..."
}

Verify a TOTP code to enable 2FA. Returns backup codes.

Request Body

Disable two-factor authentication. Requires a valid TOTP code to confirm.

Request Body

Returns all available chat channels.

Response

{
  "channels": [
    {
      "id": 1,
      "name": "general",
      "description": "General discussion",
      "is_default": 1,
      "is_stream_channel": false
    }
  ]
}

Request Body

Upload an image to embed in a chat message. Returns a URL to include as image_url in the WS message payload.

Request

Multipart form data with field name image. Max size: 5MB. Accepted types: JPEG, PNG, GIF, WebP.

Response

{
  "url": "/static/uploads/chat/abc123.jpg"
}

Fetches OpenGraph metadata (title, description, image) for a given URL. Used by the chat frontend to render link preview cards. Results are cached server-side for 1 hour.

Query Parameters

Response

{
  "url": "https://example.com/article",
  "title": "Article Title",
  "description": "A brief description...",
  "image": "https://example.com/image.jpg",
  "site_name": "Example"
}

Returns the full reply chain (thread) for a given message, walking backwards through reply_to references up to 20 messages deep. Messages are returned in chronological order (oldest first).

Response

{
  "messages": [
    {"id": 10, "username": "alice", "message": "Original message", "created_at": "..."},
    {"id": 15, "username": "bob", "message": "Reply", "reply_to": 10, "created_at": "..."},
    {"id": 20, "username": "alice", "message": "Reply to reply", "reply_to": 15, "created_at": "..."}
  ]
}

Returns STUN and optional TURN server configuration for WebRTC peer connections.

Response

{
  "ice_servers": [
    {"urls": "stun:stun.l.google.com:19302"},
    {"urls": "turn:turn.example.com:3478", "username": "user", "credential": "pass"}
  ]
}

Returns all DM conversations for the authenticated user, ordered by most recent activity. Includes the last message preview and unread count for each conversation.

Response

{
  "conversations": [
    {
      "id": 1,
      "type": "direct",
      "name": null,
      "participants": [
        {"user_id": 1, "username": "alice"},
        {"user_id": 2, "username": "bob"}
      ],
      "last_message": {
        "message": "Hey, are you around?",
        "username": "alice",
        "created_at": "2026-02-11T14:30:00"
      },
      "unread_count": 2,
      "muted": false,
      "created_at": "2026-02-11T10:00:00"
    },
    {
      "id": 2,
      "type": "group",
      "name": "Project Team",
      "participants": [
        {"user_id": 1, "username": "alice"},
        {"user_id": 2, "username": "bob"},
        {"user_id": 3, "username": "charlie"}
      ],
      "last_message": {
        "message": "Meeting at 3pm",
        "username": "charlie",
        "created_at": "2026-02-11T13:00:00"
      },
      "unread_count": 0,
      "muted": false,
      "created_at": "2026-02-10T09:00:00"
    }
  ]
}

Create a new DM conversation. For 1:1 conversations, provide user_id. For group DMs, provide user_ids array and an optional name. If a 1:1 conversation already exists with the given user, the existing conversation is returned.

Request Body (1:1)

Request Body (Group)

Response

{
  "id": 3,
  "type": "direct",
  "name": null,
  "participants": [
    {"user_id": 1, "username": "alice"},
    {"user_id": 4, "username": "dave"}
  ],
  "created_at": "2026-02-11T15:00:00"
}

Returns details for a specific DM conversation. Only accessible by conversation participants.

Response

{
  "id": 1,
  "type": "direct",
  "name": null,
  "participants": [
    {"user_id": 1, "username": "alice", "nickname": "Ali", "role": "user", "avatar": {"color": "#3b82f6", "emoji": "🚀"}},
    {"user_id": 2, "username": "bob", "nickname": null, "role": "admin", "avatar": {"color": "#ef4444", "emoji": "🔥"}}
  ],
  "muted": false,
  "created_at": "2026-02-11T10:00:00"
}

Returns messages for a DM conversation with pagination support. Messages are returned in reverse chronological order (newest first). Only accessible by conversation participants.

Query Parameters

Response

{
  "messages": [
    {
      "id": 150,
      "user_id": 1,
      "username": "alice",
      "nickname": "Ali",
      "avatar": {"color": "#3b82f6", "emoji": "🚀"},
      "message": "Hey, are you around?",
      "created_at": "2026-02-11T14:30:00"
    },
    {
      "id": 149,
      "user_id": 2,
      "username": "bob",
      "nickname": null,
      "avatar": {"color": "#ef4444", "emoji": "🔥"},
      "message": "Sure, what's up?",
      "created_at": "2026-02-11T14:29:00"
    }
  ],
  "has_more": true
}

Mute or unmute a DM conversation. Muted conversations do not generate notifications. Only accessible by conversation participants.

Request Body

Response

{
  "success": true,
  "muted": true
}

Leave a group DM conversation. Only available for group conversations (not 1:1). The conversation remains for other participants. Only accessible by conversation participants.

Response

{
  "success": true
}

Add users to an existing group DM conversation. Only available for group conversations. Total participants cannot exceed 10. Only accessible by existing conversation participants.

Request Body

Response

{
  "success": true,
  "participants": [
    {"user_id": 1, "username": "alice"},
    {"user_id": 2, "username": "bob"},
    {"user_id": 3, "username": "charlie"},
    {"user_id": 5, "username": "eve"}
  ]
}

Search across channel messages and DM conversations. Rate limited to 10 requests per minute per user.

Query Parameters

Response

{
  "results": [
    {
      "id": 42,
      "source": "channel",
      "channel_id": 1,
      "channel_name": "general",
      "user_id": 1,
      "username": "alice",
      "message": "Has anyone tried the new deployment script?",
      "created_at": "2026-02-11T12:00:00"
    },
    {
      "id": 88,
      "source": "dm",
      "conversation_id": 3,
      "conversation_name": "bob",
      "user_id": 2,
      "username": "bob",
      "message": "I deployed it yesterday, works great",
      "created_at": "2026-02-11T12:05:00"
    }
  ],
  "total": 2,
  "limit": 25,
  "offset": 0
}

Returns notifications for the authenticated user with an unread count.

Query Parameters

Response

{
  "notifications": [
    {
      "id": 1,
      "type": "stream_live",
      "title": "Stream Live",
      "message": "alice started streaming",
      "is_read": false,
      "created_at": "2026-02-08T12:00:00"
    }
  ],
  "unread_count": 3
}

Mark a single notification as read. Only affects notifications owned by the authenticated user.

Response

{
  "success": true
}

Mark all notifications as read for the authenticated user.

Response

{
  "success": true,
  "count": 5
}

Returns the list of users you have blocked. Scoped to the authenticated user.

Response

{
  "blocked_users": [
    {"id": 5, "username": "bob", "blocked_at": "2026-02-13T10:00:00"}
  ]
}

Block a user by their ID. You cannot block yourself. Blocked users' messages are hidden in chat and DMs are prevented bidirectionally.

Response

{
  "success": true
}

Remove a user from your block list.

Response

{
  "success": true
}

Lightweight user search accessible to all authenticated users. Returns basic info only (id, username, nickname). Used for DM creation and channel member management.

Query Parameters

Response

{
  "users": [
    {"id": 2, "username": "alice", "nickname": "Ali"},
    {"id": 3, "username": "bob", "nickname": null}
  ]
}

List members of a channel. Visible to channel members and moderators+.

Response

{
  "members": [
    {"user_id": 2, "username": "alice", "role": "moderator", "added_at": "2026-02-13T10:00:00"},
    {"user_id": 3, "username": "bob", "role": "member", "added_at": "2026-02-13T10:05:00"}
  ]
}

Add a user as a member of a private channel. Requires admin, channel creator, or channel moderator role.

Request Body

{
  "user_id": 5
}

Response

{
  "success": true
}

Change a channel member's role (member or moderator). Requires admin or channel creator.

Request Body

{
  "role": "moderator"
}

Remove a user from a private channel. Requires admin, channel creator, or channel moderator role.

Response

{
  "success": true
}

Create an outgoing or incoming webhook. Maximum 25 webhooks per user. The webhook secret is returned only once on creation.

Request Body

Response

{
  "id": 1,
  "name": "My Webhook",
  "type": "outgoing",
  "url": "https://example.com/hook",
  "secret": "abc123...",
  "events": ["message.created"],
  "enabled": true,
  "token": null
}

Note: The secret field is only returned on creation. Store it securely for HMAC verification.

List your webhooks. Admins see all webhooks with owner usernames. Secrets are never returned in list responses.

{
  "webhooks": [
    {
      "id": 1,
      "name": "My Webhook",
      "type": "outgoing",
      "url": "https://example.com/hook",
      "has_secret": true,
      "events": ["message.created"],
      "enabled": true,
      "consecutive_failures": 0,
      "created_at": "2026-02-19 12:00:00"
    }
  ]
}

Get details for a specific webhook. Owner or admin required.

Update webhook name, URL, events, channel, or enabled status. URL changes are SSRF-validated. Owner or admin required.

Request Body

Delete a webhook and all its delivery logs. Owner or admin required.

View delivery logs for a webhook. Includes request payload, response status, success/failure, attempt number, and duration. Logs are encrypted at rest and auto-cleaned after 7 days.

Query Parameters

Send a webhook.test event to verify your webhook endpoint is working. Owner or admin required.

Generate a new HMAC signing secret. The new secret is returned only once. The old secret is immediately invalidated.

Post a message to a chat channel via an incoming webhook. No authentication required — the token in the URL acts as the credential. Rate limited to 10 messages per 60 seconds per token.

Request Body

Outgoing Webhook Payload Format

Outgoing webhooks receive a signed JSON POST with this structure:

{
  "event": "message.created",
  "timestamp": "2026-02-19T12:00:00Z",
  "data": {
    "message_id": 123,
    "channel_id": 1,
    "channel_name": "general",
    "user_id": 10,
    "username": "alice",
    "content": "Hello world"
  }
}

Headers:
  X-Portal-Signature: sha256=abc123...
  X-Portal-Event: message.created
  Content-Type: application/json

Verify the signature by computing HMAC-SHA256(secret, request_body) and comparing with the X-Portal-Signature header value.

Opens the embedded browser page for browsing a remote web service through Portal. Requires authentication. The connection must use the http_proxy plugin type (includes http, https, http_proxy, and all web panel connection types such as Home Assistant, Grafana, Portainer, etc.). Connections with browser_mode: true support multi-site navigation to any website.

Query Parameters

Notes

• This is the user-facing page for HTTP/HTTPS connections. When users click Connect on a web-type connection, they are directed here.
• Supports tabbed browsing (Ctrl+T new tab, Ctrl+W close, Ctrl+Tab switch), keyboard shortcuts (Alt+arrows, Ctrl+L, Ctrl+R), and middle-click to close tabs.
• Browser-mode connections can navigate to any website. The address bar accepts full URLs, bare hostnames (auto-prefixed with https://), and relative paths.
• All proxied traffic is routed internally through /proxy/{connection_id}/{path}. Users should use /browser?connection={id} rather than accessing /proxy/ directly.
• The embedded browser rewrites links and intercepts navigation (forms, fetch, XHR, WebSocket, Location.assign/replace, history API) to keep all traffic within Portal's proxy layer.

Proxies HTTP requests to the backend service configured for the given connection. This endpoint is used internally by the embedded browser and should not be accessed directly by users. Use /browser?connection={id} instead for the full browsing experience with navigation controls.

Path Parameters

Behavior

• Forwards all HTTP methods (GET, POST, PUT, DELETE, etc.) to the backend
• Proxies WebSocket upgrade requests for real-time features
• Enforces TLS for connections to HTTPS backends
• In browser mode, the path encodes the full target URL (e.g., /proxy/{id}/https://example.com/page) for multi-site navigation
• Localhost and private IPs are blocked for browser-mode targets
• Portal session cookies and Authorization headers are stripped from upstream requests
• Requires authentication — only the connection owner can access their proxy routes

List remote directory contents.

Query Parameters

Read remote text file for editing. Maximum file size: 5MB.

Query Parameters

Download a remote file as a streaming attachment.

Query Parameters

Upload a file to the remote server via multipart form data.

Form Fields

Request Body

Request Body

Request Body

Delete a remote file or empty directory.

Query Parameters

List contents of a directory on the VOD SFTP storage.

Query Parameters

Read a text file from VOD SFTP storage.

Query Parameters

Download a file from VOD SFTP storage as a streaming attachment.

Query Parameters

Request Body

Upload a file to VOD SFTP storage via multipart form data.

Form Fields

Request Body

Request Body

Delete a file or empty directory from VOD SFTP storage.

Query Parameters

Returns recent activity entries. Admins see all activity; regular users see only their own.

Query Parameters

Response

{
  "activities": [
    {
      "id": 1,
      "user_id": 10,
      "username": "john",
      "action": "stream_started",
      "details": "Started streaming",
      "created_at": "2026-02-08T12:00:00"
    }
  ]
}