List nodes | Headscale unofficial

1 parameter

userstringoptional

Filter the returned nodes by user.

2 status codes

200Returns a `nodes` array containing node objects with their identifiers, names, user associations, keys, addresses, status, and route details.

nodesarray<object>required

defaultError

detailstringoptional

A human-readable explanation specific to this occurrence of the problem.

errorsarray<object>optional

Optional list of individual error details

instancestringoptional

A URI reference that identifies the specific occurrence of the problem.

statusintegeroptional

HTTP status code

titlestringoptional

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestringoptional

A URI reference to human-readable documentation for the error.

Default:about:blank

Error handling

The user query parameter is a string used to filter nodes by user.

import { Client } from "headscale-unofficial-sdk";

const client = new Client({
  baseUrl: "https://api.acme.com",
  auth: { bearer: process.env.API_TOKEN },
});

const result = await client.node.list({ user: "octocat" });

{
  "nodes": [
    {
      "approvedRoutes": [
        "example_value"
      ],
      "availableRoutes": [
        "example_value"
      ],
      "createdAt": "2026-01-15T09:00:00Z",
      "discoKey": "example_key_abc123",
      "expiry": "2026-01-15T09:00:00Z",
      "givenName": "Example Name",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "ipAddresses": [
        "example_value"
      ],
      "lastSeen": "2026-01-15T09:00:00Z",
      "machineKey": "example_key_abc123",
      "name": "Example Name",
      "nodeKey": "example_key_abc123",
      "online": true,
      "preAuthKey": {
        "aclTags": [
          "example_value"
        ],
        "createdAt": "2026-01-15T09:00:00Z",
        "ephemeral": true,
        "expiration": "2026-01-15T09:00:00Z",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "key": "example_key_abc123",
        "reusable": true,
        "used": true,
        "user": {
          "createdAt": "2026-01-15T09:00:00Z",
          "displayName": "Example Name",
          "email": "user@example.com",
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Example Name",
          "profilePicUrl": "https://example.com",
          "provider": "Example Academy Trust",
          "providerId": "550e8400-e29b-41d4-a716-446655440000"
        }
      },
      "registerMethod": "REGISTER_METHOD_UNSPECIFIED",
      "subnetRoutes": [
        "example_value"
      ],
      "tags": [
        "example_value"
      ],
      "user": {
        "createdAt": "2026-01-15T09:00:00Z",
        "displayName": "Example Name",
        "email": "user@example.com",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Example Name",
        "profilePicUrl": "https://example.com",
        "provider": "Example Academy Trust",
        "providerId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  ]
}

Request

Response

Errors