orpheagentVersion 1.1.9
API Endpoints
OrpheAgent RESTful API, WebSocket, authentication, and Data Plane endpoint reference.
OrpheAgent API Endpoints
OrpheAgent provides RESTful API and WebSocket endpoints for managing configuration, system information, the Control Plane, the Data Plane, service status, and device verification. Unless noted otherwise, the paths below use /api/v1 as the Base URL.
Swagger UI
Replace {ORPHEAGENT_HOST} with the IP address or domain name of the host running OrpheAgent, then open:
http://{ORPHEAGENT_HOST}/swagger/index.html#/
- Non-release build: Swagger UI is available when the Agent runs in debug foreground mode.
orphe-agent up -f -d - Release build: Swagger UI is not registered.
Authentication
Protected endpoints validate the Authorization header. Middleware bypasses token validation when the request originates from 127.0.0.1. WebSocket and browser-based flows can also pass the same token through the token query parameter.
The Authentication column follows the source API reference. — means that the source does not state an authentication requirement.
Develop
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /develop/ws/terminal | Opens a WebSocket connection to the web terminal execution session. | Required |
| GET | /develop/debug/memory | Returns Go runtime memory statistics. | Required |
| POST | /develop/debug/memory/free | Runs garbage collection, returns memory to the OS, and returns updated statistics. | Required |
Dashboards
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /dashboards/get | Retrieves system dashboard information, including CPU, memory, and disk usage. | Required |
System
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /system/info | Retrieves the OrpheAgent software version and related information. | Required |
| GET | /system/update/check | Checks whether a newer OrpheAgent version is available. | Required |
| POST | /system/update/install | Downloads and installs the latest version in the background. | Required |
| GET | /system/update/progress | Retrieves the progress of the current update operation. | Required |
Control Plane
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /controlplane/status | Retrieves the provision state and OrpheLink connection status. | Required |
| GET | /controlplane/dht | Retrieves whether DHT is enabled for the Control Plane. | Required |
| POST | /controlplane/dht | Enables or disables DHT for the Control Plane. | Required |
| GET | /controlplane/relayaddrs | Retrieves self-owned relay addresses for the Control Plane. | Required |
| POST | /controlplane/relayaddrs | Updates self-owned relay addresses for the Control Plane. | Required |
Configuration
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| POST | /config | Saves the complete configuration. | Required |
| POST | /config/basic | Saves only the host name and Provision Key. | Required |
| GET | /config | Loads the current configuration. | Required |
Network
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /network/statistics/ws | Provides network traffic statistics over WebSocket. | — |
| GET | /network/nat/type | Detects and returns the current NAT type. | — |
Jump to Service
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| POST | /jumptoservice/config | Saves the Jump-to-Service configuration. | Required |
| GET | /jumptoservice/config | Loads the Jump-to-Service configuration. | Required |
| DELETE | /jumptoservice/config/:name | Deletes the named Jump-to-Service configuration. | Required |
Service
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /service/status/ws | Streams OrpheAgent and OrpheLink connection status over a persistent WebSocket. | Required |
| GET | /service/toggle | Retrieves the Control Plane and Data Plane toggle states. | Required |
| POST | /service/toggle | Enables or disables the Control Plane and/or Data Plane. | Required |
Device Auth
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /deviceauth/status | Retrieves the device Magic Link state and whether the Data Plane is allowed. | Required |
| POST | /deviceauth/send | Requests a verification Magic Link; /deviceauth/resend is an alias for the same endpoint. | Required |
Magic Links are never sent automatically. The Agent reports magicLinkAutoSend: false; after a device wakes from sleep or the Control Plane restarts, it remains in awaiting_request until the user runs orphe-agent device-auth --send to request a link.
Profile
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| POST | /profile | Creates a configuration profile. | Required |
| GET | /profile | Retrieves the configuration profile list. | Required |
| DELETE | /profile | Deletes a configuration profile. | Required |
| POST | /profile/use | Makes a configuration profile active. | Required |
Data Plane
Nodes and Neighbors
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /dataplane/node | Retrieves Data Plane node information. | Required |
| POST | /dataplane/node | Updates Data Plane node information. | Required |
| POST | /dataplane/neighbor/add | Adds a neighbor. | Required |
| POST | /dataplane/neighbor/edit/:id | Edits a neighbor. | Required |
| POST | /dataplane/neighbor/delete/:id | Deletes a neighbor. | Required |
Data Plane Control
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| POST | /dataplane/start | Starts the Data Plane. | Required |
| POST | /dataplane/stop | Stops the Data Plane. | Required |
| POST | /dataplane/restart | Restarts the Data Plane. | Required |
| GET | /dataplane/status | Retrieves the current Data Plane status. | Required |
| GET | /dataplane/status/ws | Streams node, neighbor, traffic, OS, device-name, and P2P-quality status over a persistent WebSocket. | Required |
| POST | /dataplane/status/:status | Updates the Data Plane status. | Required |
Routing and Relay Addresses
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /dataplane/routesubnettoexit | Retrieves subnets routed to the exit node. | Required |
| POST | /dataplane/routesubnettoexit | Configures subnets to route to the exit node. | Required |
| GET | /dataplane/relayaddrs | Retrieves relay addresses used by the Data Plane. | Required |
| POST | /dataplane/relayaddrs | Updates Data Plane relay addresses. | Required |
Port Forwarding
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /dataplane/portforwarding/list | Lists all port-forwarding rules. | Required |
| POST | /dataplane/portforwarding/add | Adds a port-forwarding rule. | Required |
| POST | /dataplane/portforwarding/delete/:name | Deletes a port-forwarding rule by name. | Required |
Access Control List (ACL)
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| POST | /dataplane/acl/mode/:mode | Sets the Data Plane ACL mode. | Required |
| GET | /dataplane/acl/mode | Retrieves the current ACL mode. | Required |
| GET | /dataplane/acl/list | Lists all ACL rules. | Required |
| POST | /dataplane/acl | Adds an ACL rule. | Required |
| DELETE | /dataplane/acl | Deletes an ACL rule. | Required |
Services, MTU, and Tunnel Mode
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /dataplane/services/list | Lists all Data Plane services. | Required |
| POST | /dataplane/services/edit | Edits a Data Plane service. | Required |
| POST | /dataplane/services/edit/{id} | Edits services for the specified neighbor or node ID. | Required |
| GET | /dataplane/mtu | Retrieves MTU settings. | Required |
| POST | /dataplane/mtu | Updates MTU settings. | Required |
| GET | /dataplane/tunnelmode | Retrieves the current tunnel mode: high throughput or low latency. | Required |
| POST | /dataplane/tunnelmode | Sets the Data Plane tunnel mode. | Required |
SNAT, Subnets, and End Devices
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /dataplane/snat | Retrieves the current SNAT setting. | Required |
| POST | /dataplane/snat/{status} | Sets the Data Plane SNAT state. | Required |
| GET | /dataplane/subnetlist | Retrieves the Data Plane subnet list. | Required |
| GET | /dataplane/enddevicelist | Retrieves the Data Plane end-device list. | Required |
DHT and NAT Type
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /dataplane/dht/{id} | Retrieves whether DHT is enabled for the specified node. | Required |
| POST | /dataplane/dht/{id} | Enables or disables DHT for the specified node. | Required |
| GET | /dataplane/nat/type/{id} | Retrieves the NAT type for the specified node. | Required |
Exit Nodes and LAN Sharing
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /dataplane/exitnode/list | Retrieves available exit nodes from the neighbor list. | Required |
| GET | /dataplane/exitnode/config/{id} | Retrieves exit-node configuration for a node. | Required |
| POST | /dataplane/exitnode/config/{id} | Sets exit-node configuration for a node. | Required |
| GET | /dataplane/lan/subnetsharing/config/{id} | Retrieves LAN subnet-sharing configuration for a node. | Required |
| POST | /dataplane/lan/subnetsharing/config/{id} | Sets LAN subnet-sharing configuration for a node. | Required |
Route to Exit and Device Configuration
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| GET | /dataplane/routetoexit/config/{id} | Retrieves Route-to-Exit configuration for a node. | Required |
| POST | /dataplane/routetoexit/config/{id} | Routes a node's traffic through the configured exit node. | Required |
| POST | /dataplane/config/rename/{id} | Renames device configuration for a node. | Required |
Portal Authentication and Hole-Punch Events
| Method | Endpoint | Function | Authentication |
|---|---|---|---|
| POST | /dataplane/portal/login | Handles Portal login authentication. | — |
| GET | /dataplane/holepunchevent/ws | Streams NAT address exchange, hole-punch attempts, and peer connection status over WebSocket. | Required |