User Manual
API Endpoints
Version 1.1.9
Swagger UI Interface
OrpheAgent provides a Swagger UI interface for users to test APIs at http:// {ORPHEAGENT_HOST } /swagger/index.html#/
(Replace {ORPHEAGENT_HOST} with the IP address or domain name of the server where OrpheAgent is running.)
- Non-release build: Swagger UI is available when the agent is started in debug foreground mode
orphe-agent up -f -d - Release build: Swagger UI is not registered.
The OrpheAgent provides a comprehensive set of RESTful API endpoints for managing configurations, dashboards, networks, and data plane functionalities. These endpoints are designed to facilitate secure and efficient operations, leveraging authentication and WebSocket capabilities where applicable.
General Information
- Base URL:
/api/v1 - Authentication: Protected endpoints use the
Authorizationheader. When the request source is127.0.0.1, the middleware bypasses token validation. For WebSocket and browser-based flows, the same token can also be passed as thetokenquery parameter.
Endpoints
Develop
- WebSocket Terminal:
/develop/ws/terminal(GET)- Opens a WebSocket connection to the execution session of the web terminal.
- Requires authentication.
- Debug Memory Stats:
/develop/debug/memory(GET)- Returns Go runtime memory statistics for debugging purposes.
- Requires authentication.
- Free OS Memory:
/develop/debug/memory/free(POST)- Forces garbage collection and returns memory to the OS, then returns updated memory statistics.
- Requires authentication.
Dashboards
- Get Dashboard Info:
/dashboards/get(GET)- Retrieves system dashboard information, including CPU, memory, and disk usage.
- Requires authentication.
System
- Get System Info:
/system/info(GET)- Retrieves software version and related information of OrpheAgent.
- Requires authentication.
- Check Update:
/system/update/check(GET)- Checks if a newer version of OrpheAgent is available.
- Requires authentication.
- Install Update:
/system/update/install(POST)- Starts downloading and installing the latest update in the background.
- Requires authentication.
- Get Update Progress:
/system/update/progress(GET)- Retrieves the current progress of an ongoing update.
- Requires authentication.
ControlPlane
- Get Control Plane Status:
/controlplane/status(GET)- Retrieves the current control plane status, including the provision state and OrpheLink connection status.
- Requires authentication.
- Get DHT Config:
/controlplane/dht(GET)- Retrieves whether DHT is enabled for the control plane.
- Requires authentication.
- Set DHT Config:
/controlplane/dht(POST)- Enables or disables DHT for the control plane.
- Requires authentication.
- Get Relay Addresses:
/controlplane/relayaddrs(GET)- Retrieves self-owned relay addresses from the control plane.
- Requires authentication.
- Set Relay Addresses:
/controlplane/relayaddrs(POST)- Updates self-owned relay addresses for the control plane.
- Requires authentication.
Configuration
- Save Configuration:
/config(POST)- Saves the provided configuration.
- Requires authentication.
- Save Basic Configuration:
/config/basic(POST)- Saves the basic configuration of the OrpheAgent (hostname and provision key only).
- Requires authentication.
- Load Configuration:
/config(GET)- Loads the current configuration.
- Requires authentication.
Network
- Get Network Statistics:
/network/statistics/ws(GET)- Provides WebSocket-based network traffic statistics.
- Provides WebSocket-based network traffic statistics.
- Get NAT Type:
/network/nat/type(GET)- Detects and returns the current NAT type of the network.
Jump to Service
- Save Configuration:
/jumptoservice/config(POST)- Saves the jump-to-service configuration.
- Requires authentication.
- Load Configuration:
/jumptoservice/config(GET)- Loads the jump-to-service configuration.
- Requires authentication.
- Delete Configuration:
/jumptoservice/config/:name(DELETE)- Deletes the specified jump-to-service configuration.
- Requires authentication
Service
- Get Service Status WebSocket:
/service/status/ws(GET)- Provides real-time notification of OrpheAgent and OrpheLink connection status via WebSocket.
- Maintains persistent WebSocket connection for streaming service status updates.
- Requires authentication.
- Get Service Toggle Status:
/service/toggle(GET)- Retrieves the current toggle state of the service (Control Plane and Data Plane status).
- Returns boolean flags for each service component.
- Requires authentication.
- Set Service Toggle Status:
/service/toggle(POST)- Enables or disables Control Plane and/or Data Plane.
- Requires authentication.
- Set Service Toggle Status:
/service/toggle(POST)- Enables or disables Control Plane and/or Data Plane.
- Requires authentication.
DeviceAuth
- Get Device Magic Link Status:
/deviceauth/status(GET)- Retrieves the device magic link verification state and whether the data plane is allowed.
- Requires authentication.
- Send or Resend Device Magic Link:
/deviceauth/send(POST, alias/deviceauth/resend)- Requests that the controller email a verification magic link for the current control session. Links are never sent automatically: the agent reports
magicLinkAutoSend: false, so a device that reconnects (sleep and wake, control plane restart) sits in theawaiting_requeststate until the user asks for a link withorphe-agent device-auth --send. - Requires authentication.
- Requests that the controller email a verification magic link for the current control session. Links are never sent automatically: the agent reports
Profile
- Create Profile:
/profile(POST)- Creates a new configuration profile.
- Requires authentication.
- Get Profiles:
/profile(GET)- Retrieves the list of configuration profiles.
- Requires authentication.
- Delete Profile:
/profile(DELETE)- Deletes a configuration profile.
- Requires authentication.
- Use Profile:
/profile/use(POST)- Sets a configuration profile as the active profile.
- Requires authentication.
DataPlane
- Node Management:
- Get Node:
/dataplane/node(GET)- Retrieves node information from the data plane.
- Requires authentication.
- Set Node:
/dataplane/node(POST)- Updates node information in the data plane.
- Requires authentication.
- Get Node:
- Neighbor Management:
- Add Neighbor:/dataplane/neighbor/add (POST)
- Adds a new neighbor to the data plane.
- Requires authentication.
- Edit Neighbor:
/dataplane/neighbor/edit/:id(POST)- Edits an existing neighbor in the data plane.
- Requires authentication.
- Delete Neighbor:
/dataplane/neighbor/delete/:id(POST)- Deletes a neighbor from the data plane.
- Requires authentication.
- Add Neighbor:/dataplane/neighbor/add (POST)
- Dataplane Control:
- Start:
/dataplane/start(POST)- Starts the dataplane.
- Requires authentication.
- Stop:
/dataplane/stop(POST)- Stops the data plane.
- Requires authentication.
- Restart:
/dataplane/restart(POST)- Restarts the data plane.
- Requires authentication.
- Get Status:
/dataplane/status(GET)- Retrieves the current status of the data plane.
- Requires authentication.
- Get Status WebSocket:
/dataplane/status/ws(GET)- Provides real-time data plane status via WebSocket.
- Returns comprehensive status information including node status, neighbor information, traffic statistics, OS information, device name, and P2P connection quality assessment.
- Maintains persistent WebSocket connection for streaming status updates.
- Requires authentication.
- Set Status:
/dataplane/status/:status(POST)- Updates the status of the data plane.
- Requires authentication.
- Start:
- Routing:
- Get Route Subnet to Exit:
/dataplane/routesubnettoexit(GET)- Retrieves subnets routed to the exit node in the data plane.
- Requires authentication.
- Set Route Subnet to Exit:
/dataplane/routesubnettoexit(POST)- Configures subnets to route to the exit node in the data plane.
- Requires authentication.
- Get Route Subnet to Exit:
- Relay Addresses:
- Get Relay Addresses:
/dataplane/relayaddrs(GET)- Retrieves relay addresses used by the data plane.
- Requires authentication.
- Set Relay Addresses:
/dataplane/relayaddrs(POST)- Updates relay addresses for the data plane.
- Requires authentication.
- Get Relay Addresses:
- Port Forwarding:
- List:
/dataplane/portforwarding/list(GET)- Lists all port forwarding rules.
- Requires authentication.
- Add:
/dataplane/portforwarding/add(POST)- Adds a new port forwarding rule.
- Requires authentication.
- Delete:
/dataplane/portforwarding/delete/:name(POST)- Deletes a port forwarding rule by name.
- Requires authentication.
- List:
- Access Control List (ACL):
- Set Mode:
/dataplane/acl/mode/:mode(POST)- Sets the ACL mode for the data plane.
- Requires authentication.
- Get Mode:
/dataplane/acl/mode(GET)- Retrieves the current ACL mode of the data plane.
- Requires authentication.
- List:
/dataplane/acl/list(GET)- Lists all ACL rules in the data plane.
- Requires authentication.
- Add:
/dataplane/acl(POST)- Adds a new ACL rule to the data plane.
- Requires authentication.
- Delete:
/dataplane/acl(DELETE)- Deletes an ACL rule from the data plane.
- Requires authentication.
- Set Mode:
- Services:
- List Services:
/dataplane/services/list(GET)- Lists all services in the dataplane.
- Requires authentication.
- Edit Service:
/dataplane/services/edit(POST)- Edits an existing service in the data plane.
- Requires authentication.
- Edit Service:
/dataplane/services/edit(POST)- Edits an existing service in the data plane.
- Requires authentication.
- Edit Service by Node:
/dataplane/services/edit/{id}(POST)- Edits services for the specified neighbor or node ID.
- Requires authentication.
- List Services:
- MTU:
- Get MTU:
/dataplane/mtu(GET)- Retrieves the Maximum Transmission Unit (MTU) settings.
- Requires authentication.
- Set MTU:
/dataplane/mtu(POST)- Updates the MTU settings.
- Requires authentication.
- Get MTU:
- Tunnel Mode:
- Get Tunnel Mode:
/dataplane/tunnelmode(GET)- Retrieves the current tunnel mode setting of the data plane (high throughput or low latency).
- Requires authentication.
- Set Tunnel Mode:
/dataplane/tunnelmode(POST)- Sets the tunnel mode for the data plane to optimize for either high throughput or low latency.
- Requires authentication.
- Get Tunnel Mode:
- SNAT (Source Network Address Translation):
- Get SNAT:
/dataplane/snat(GET)- Retrieves the current SNAT (Source Network Address Translation) setting of the data plane.
- Requires authentication.
- Set SNAT:
/dataplane/snat/{status}(POST)- Sets the SNAT (Source Network Address Translation) for the data plane.
- Requires authentication.
- Get SNAT:
- Subnet and End Device:
- Get Subnet List:
/dataplane/subnetlist(GET)- Retrieves a list of subnets in the data plane.
- Requires authentication.
- Get End Device List:
/dataplane/enddevicelist(GET)- Retrieves a list of end devices in the data plane.
- Requires authentication.
- Get Subnet List:
- DHT Configuration:
- Get DHT Config:
/dataplane/dht/{id}(GET)- Retrieves whether DHT is enabled for the specified node.
- Requires authentication.
- Set DHT Config:
/dataplane/dht/{id}(POST)- Enables or disables DHT for the specified node.
- Requires authentication.
- Get DHT Config:
- NAT Type:
- Get NAT Type:
/dataplane/nat/type/{id}(GET)- Retrieves the NAT type for the specified node.
- Requires authentication.
- Get NAT Type:
- Exit Node Configuration:
- Get Exit Node List:
/dataplane/exitnode/list(GET)- Retrieves the list of available exit nodes from neighbors.
- Requires authentication.
- Get Exit Node Config:
/dataplane/exitnode/config/{id}(GET)- Retrieves the exit node configuration for a specific node.
- Requires authentication.
- Set Exit Node Config:
/dataplane/exitnode/config/{id}(POST)- Sets the exit node configuration for a specific node.
- Requires authentication.
- Get Exit Node List:
- LAN Subnet Sharing:
- Get LAN Subnet Sharing Config:
/dataplane/lan/subnetsharing/config/{id}(GET)- Retrieves the LAN subnet sharing configuration for a specific node.
- Requires authentication.
- Set LAN Subnet Sharing Config:
/dataplane/lan/subnetsharing/config/{id}(POST)- Sets the LAN subnet sharing configuration for a specific node.
- Requires authentication.
- Get LAN Subnet Sharing Config:
- Route to Exit:
- Get Route to Exit Config:
/dataplane/routetoexit/config/{id}(GET)- Retrieves the route to exit node configuration for a specific node.
- Requires authentication.
- Set Route to Exit Config:
/dataplane/routetoexit/config/{id}(POST)- Sets the route to exit node configuration for a specific node, directing traffic through the specified exit node.
- Requires authentication.
- Get Route to Exit Config:
- Device Configuration:
- Rename Device Config:
/dataplane/config/rename/{id}(POST)- Renames the device configuration with a new device name for a specific node.
- Requires authentication.
- Rename Device Config:
- Portal Authentication:
- Login:
/dataplane/portal/login(POST)- Handles the authentication for the portal.
- Login:
- Hole Punch Event:
- Get Hole Punch Event:
/dataplane/holepunchevent/ws(GET)- Handles WebSocket connections for hole punching events.
- Provides real-time notifications about NAT traversal attempts, including address exchange, hole punch attempts, and connection status updates between peers.
- Requires authentication.
- Get Hole Punch Event:
