Skip to main content

Dashboard API documentation

info

This documentation is for Husarnet Dashboard API v3, which is currently in Beta. If you want to try this one out, you need an account at the Beta Dashboard and Husarnet version 2.0.335 or later (nightly channel).

If you are looking for legacy API docs, please refer to Legacy Dashboard API documentation.

Introduction​

If you want to automate some part of your Husarnet workflow, or simply prefer TUIs over modern webapps, you can utilize our HTTP API for fleet management. The API can do anything the Dashboard can do, as this is exactly the same API the Dashboard is using itself.

The API can be accessed in three ways:

  • CLI - via Husarnet CLI commands like husarnet group create (easiest, cross-platform, most user-friendly and strongly recommended);
  • Daemon-proxied - by sending HTTP requests to /forward endpoint in Husarnet Daemon API (those are signed by the Daemon and forwarded to the Dashboard API);
  • Direct with JWT - by sending HTTP requests to API endpoints directly (which requires authentication in separate microservice in order to obtain bearer token);

Setup and authentication​

Ensure that on the machine you want to use the API from:

  • You have administrator privileges;
  • Husarnet is installed and connected to the Dashboard;
  • The device has AccountAdmin flag enabled in the Dashboard;

account admin flag

Husarnet Daemon provides the authentication layer in this case, and this is happening transparently. You are good to go.

Remember only the administrator of the device can use the API. You can for example: prefix each command with sudo (Linux, MacOS), add your user to husarnet group (Linux) or use elevated command prompt (Windows).

General info​

API responses are always JSON and follow the structure below:

{
  "type": "success",
  "errors": [],
  "warnings": [],
  "message": "OK",
  "payload": {}
}
  • type can be success, user_error (for example incorrect input parameters) or server_error.
  • errors, warnings and message will contain additional information that you may examine to see what was the problem if the request failed.
  • actual thing you are requesting is in payload field, which can be an object or an array of objects, depending on the endpoint.
caution

Be aware of the non-traditional behavior! In case of recoverable/temporary server errors, API will return status 200 anyway and type will be set to server_error. Always check type field when consuming API responses.

If you use the CLI, you can add --json or -j parameter, as used in the examples below, to display full JSON output. In the examples we also use --indent-json or -i, which indents the JSON. Without this parameter JSON is outputted in the most compact form (machine-friendly).

Skipping --json parameter outputs tabular data intended for human glance and is not suitable for scripts.

Groups​

Listing your groups​

husarnet --json -i group ls

Example output:

{
  "type": "success",
  "errors": [],
  "warnings": [],
  "message": "OK",
  "payload": [
    {
      "id": "36dc59ab-f75f-488d-86bf-e0696fb88eb0",
      "emoji": "🪟",
      "name": "main",
      "comment": "",
      "devices": [
        {
          "id": "c3ca3ded-02cd-4be3-b291-8a5576437fa0",
          "ip": "fc94:dede:eeee:dede:eeee:dede:eeee:dede",
          "emoji": "🤖",
          "hostname": "macos-testing",
          "userAgent": "Husarnet,MacOS,ARM64,2.0.330",
          "comment": "",
          "aliases": null,
          "status": "on",
          "lastContact": "2025-11-17T10:35:40.819937Z"
        },
        {
          "id": "14fe531e-c72e-45b3-b3f5-17ca2188a4f5",
          "ip": "fc94:dede:eeee:dede:eeee:dede:eeee:dede",
          "emoji": "🤖",
          "hostname": "gnaarmok",
          "userAgent": "Husarnet,Linux,AMD64,2.0.333",
          "comment": "",
          "aliases": null,
          "status": "off",
          "lastContact": "2025-11-17T10:35:51.460052Z"
        }
      ]
    },
    {
      "id": "c1a307df-1285-4199-94ff-8d9ef6eb356f",
      "emoji": "😄",
      "name": "esp32-homelab",
      "comment": "",
      "devices": null
    },
    {
      "id": "863d0102-8eda-4687-91ad-0f385c67d7b3",
      "emoji": "🤖",
      "name": "robots",
      "comment": "",
      "devices": null
    }
  ]
}

Viewing a group​

husarnet --json -i group show <group name or id>

You can provide group name as an argument here. The CLI will figure out the correct UUID. You can also provide group UUID directly.

Example output:

{
  "type": "success",
  "errors": [],
  "warnings": [],
  "message": "OK",
  "payload": {
    "group": {
      "id": "36dc59ab-f75f-488d-86bf-e0696fb88eb0",
      "emoji": "🪟",
      "name": "main",
      "comment": "",
      "devices": [
        {
          "id": "14fe531e-c72e-45b3-b3f5-17ca2188a4f5",
          "ip": "fc94:dede:eeee:dede:eeee:dede:eeee:dede",
          "emoji": "🤖",
          "hostname": "gnaarmok",
          "userAgent": "Husarnet,Linux,AMD64,2.0.333",
          "comment": "",
          "aliases": null,
          "status": "",
          "lastContact": "2025-11-17T10:38:51.905168Z"
        },
        {
          "id": "c3ca3ded-02cd-4be3-b291-8a5576437fa0",
          "ip": "fc94:dede:eeee:dede:eeee:dede:eeee:dede",
          "emoji": "🤖",
          "hostname": "macos-testing",
          "userAgent": "Husarnet,MacOS,ARM64,2.0.330",
          "comment": "",
          "aliases": null,
          "status": "",
          "lastContact": "2025-11-17T10:38:41.634217Z"
        }
      ],
      "joinCodes": null
    },
    "attachableDevices": [],
    "joinCode": {
      "token": "some_token"
    }
  }
}

Creating a new group​

husarnet --json -i group create <group name>

Name is the only required parameter when creating a group. To set optional parameters, like comment, use flags (--emoji, --comment). For example:

husarnet --json -i group create new_group_name --comment "some comment"

Group name has to be at least 2 characters long and cannot exceed 100 characters. Whitespace (e.g. space character) is also not allowed. Best names are short and memorable.

Updating group information​

husarnet --json -i group update <group name or id> --name <new name>

For any existing group owned by you, you can change:

  • emoji, by passing --emoji <new emoji> parameter
  • name, by passing --name <new name> parameter
  • comment, by passing --comment <new comment> parameter

Deleting a group​

husarnet --json -i group delete <group name or id>

The CLI will ask for confirmation before sending the DELETE request.

Devices​

Listing devices​

husarnet --json -i device ls

Possible output:

{
  "type": "success",
  "errors": [],
  "warnings": [],
  "message": "OK",
  "payload": [
    {
      "id": "14fe531e-c72e-45b3-b3f5-17ca2188a4f5",
      "ip": "fc94:dede:eeee:dede:eeee:dede:eeee:dede",
      "emoji": "🤖",
      "hostname": "gnaarmok",
      "userAgent": "Husarnet,Linux,AMD64,2.0.333",
      "comment": "",
      "aliases": null,
      "status": "on",
      "lastContact": "2025-11-17T14:43:49.246282Z"
    },
    {
      "id": "c3ca3ded-02cd-4be3-b291-8a5576437fa0",
      "ip": "fc94:dede:eeee:dede:eeee:dede:eeee:dede",
      "emoji": "🤖",
      "hostname": "macos-testing",
      "userAgent": "Husarnet,MacOS,ARM64,2.0.330",
      "comment": "",
      "aliases": null,
      "status": "on",
      "lastContact": "2025-11-17T14:43:42.83495Z"
    }
  ]
}

Viewing a device​

husarnet --json -i device show <device uuid OR IPv6 addr OR hostname>

You can provide device UUID, IPv6 address or hostname as an argument here. The CLI will figure out the correct UUID to put into the request.

Example output:

{
  "type": "success",
  "errors": [],
  "warnings": [],
  "message": "OK",
  "payload": {
    "id": "14fe531e-c72e-45b3-b3f5-17ca2188a4f5",
    "ip": "fc94:7e37:b5d5:4489:261c:3899:9845:8482",
    "emoji": "🤖",
    "hostname": "gnaarmok",
    "userAgent": "Husarnet,Linux,AMD64,2.0.333",
    "comment": "",
    "aliases": null,
    "status": "on",
    "lastContact": "2025-11-17T15:06:52.958036Z"
  }
}

Attaching a device to a group​

Provide device identifier (UUID, IPv6 address or hostname) as first positional parameter, and group identifier (UUID or name) as second.

husarnet --json -i device attach [device] <group uuid OR name>

For example:

husarnet --json -i device attach gnaarmok robots

Omitting device identifier will attach the current device (the one where the command is run). The CLI will figure out the correct UUIDs to put into the request.

Detaching a device from a group​

Provide device identifier (UUID, IPv6 address or hostname) as first positional parameter, and group identifier (UUID or name) as second.

husarnet --json -i device detach [device] <group uuid OR name>

For example:

husarnet --json -i device detach gnaarmok robots

Omitting device identifier will detach the current device (the one where the command is run). The CLI will figure out the correct UUIDs to put into the request.

Updating device information​

husarnet --json -i device update <device uuid OR ip OR hostname> --hostname <new hostname>

For any existing device owned by you, you can change:

  • emoji, by passing --emoji <new emoji> parameter
  • hostname, by passing --hostname <new name> parameter
  • comment, by passing --comment <new comment> parameter