Nodes

This article refers to SDK version v0.5.0. The current SDK version is N/A.

NodesResource (available as client.nodes) covers node lifecycle actions (list, resolve, reboot, provision, deprovision...), identity (name, tags, location, safety actions), global secrets, global configuration, docker credentials and volumes, telemetry, and Barbara Core updates. See the Overview for narrative examples, and Node management for the equivalent Panel actions.

Concept

Node. The machine an operator manages from Barbara Panel: a physical gateway, a virtual machine, or a hosted sandbox, running the Barbara agent and reporting its own status and telemetry back.

Learn more→

NodesResource

NodesResource(client: BarbaraClient)

list

list(*, search: Optional[str] = None, size: Optional[int] = None) -> List[Node]

Returns a single page of nodes — the server applies its own default page size when size isn't given. Use paginate() if you need total or need to page through a large fleet.

paginate

paginate(*, search: Optional[str] = None, size: int = 50, from_: int = 0) -> Page

get

get(node_id: str) -> Node

resolve

resolve(node_name: str) -> Node

Look up a node by its Barbara ID / deviceName (not its internal _id).

delete

delete(node_id: str) -> None

add_node

add_node(
    node_names: List[str],
    assigned_names: List[str],
    tags: List[str],
    *,
    provisioned: bool = False,
    group: str = '',
    family_id: str = '',
    disk_overload: Optional[Dict[str, Any]] = None,
    gps: Optional[Dict[str, Any]] = None,
) -> None

Manually register one or more nodes (node_names, the factory-assigned serials) under their operator-facing names (assigned_names) — the two lists are matched by position. Most nodes are provisioned automatically instead; use this for manual registration flows.

get_name

get_name(node_id: str) -> str

update_name

update_name(node_id: str, name: str) -> None

add_tag

add_tag(node_id: str, tag: str) -> None

update_tags

update_tags(node_id: str, tags: List[str]) -> None

delete_tag

delete_tag(node_id: str, tag: str) -> None

list_by_tags

list_by_tags(tags: List[str]) -> List[Node]

Every node carrying at least one of the given tags. The wire's /v1/devices list endpoint has no server-side tag filter (only search/groupIds), so this pages through the whole fleet with paginate() and filters locally on each node's own tags field — fine for selecting a target set (nodes, clusters, groups), not meant for a hot path against a very large fleet.

update_safety_actions

update_safety_actions(
    node_id: str,
    *,
    trigger_threshold: float,
    stop_apps: bool = False,
    prune_all: bool = False,
    prune_images: bool = False,
    prune_containers: bool = False,
    prune_volumes: bool = False,
) -> None

Configures automatic action when disk usage crosses trigger_threshold (a percentage, strictly between 0.1 and 99.9) — stopping apps and/or pruning docker resources, without waiting for a human to react. All five action flags are always sent, and at least one of them must be true.

get_alive

get_alive(node_id: str) -> bool

get_location

get_location(node_id: str) -> Dict[str, Any]

Returned as a raw dict, since node location payloads vary in shape.

set_location

set_location(
    node_id: str,
    *,
    lat: float,
    lng: float,
    country: Optional[str] = None,
    city: Optional[str] = None,
    region: Optional[str] = None,
) -> None

Currently returns a 500 Internal Server Error regardless of the payload sent. Use the Panel to update a node's location until this is resolved.

delete_location

delete_location(node_id: str) -> None

list_groups

list_groups(node_id: str) -> List[Group]

A node can belong to more than one group, so this returns a list.

list_global_secrets

list_global_secrets(node_id: str) -> List[GlobalSecret]

create_global_secrets

create_global_secrets(node_id: str, secrets: Dict[str, str]) -> None

secrets maps plain secret name -> plain value; both are base64-encoded internally before sending, per Barbara's convention.

delete_global_secret

delete_global_secret(node_id: str, secret_id: str) -> None

delete_all_global_secrets

delete_all_global_secrets(node_id: str) -> None

get_global_secret

get_global_secret(node_id: str, secret_id: str) -> GlobalSecret

get_global_config

get_global_config(node_id: str) -> Dict[str, Any]

Returns the decoded config dict — symmetric with set_global_config(config=...). The real response wraps this in a sent/current/status propagation envelope; use client.request(...) directly if you need that envelope.

set_global_config

set_global_config(
    node_id: str,
    *,
    config: Optional[Dict[str, Any]] = None,
    config_id: Optional[str] = None,
) -> None

Either config or config_id must be given; config_id takes precedence if both are. config is JSON+base64-encoded.

list_docker_credentials

list_docker_credentials(node_id: str) -> List[DockerCredential]

The response wraps the array as {"dockerCredential": [...]}} — note the singular, camelCase key (not credentials).

get_docker_credential

get_docker_credential(node_id: str, credential_id: str) -> DockerCredential

create_docker_credentials

create_docker_credentials(node_id: str, credentials: List[Dict[str, str]]) -> None

Each item in credentials is a plain {"user", "password", "server"} dict — all three fields are base64-encoded internally.

delete_docker_credential

delete_docker_credential(node_id: str, credential_id: str) -> None

delete_all_docker_credentials

delete_all_docker_credentials(node_id: str) -> None

reboot

reboot(node_id: str, *, force: bool = False) -> None

poweroff

poweroff(node_id: str) -> None

provision

provision(node_id: str) -> None

deprovision

deprovision(node_id: str) -> None

brick

brick(node_id: str) -> None

update_barbara_core

update_barbara_core(
    node_id: str,
    update_type: str,
    *,
    incremental: bool = False,
    schedule_timestamp: Optional[str] = None,
) -> None

update_type is one of "download", "update", "schedule". schedule_timestamp (ISO 8601) is required when update_type is "schedule".

update_barbara_core_schedule

update_barbara_core_schedule(
    node_id: str,
    update_type: str,
    *,
    incremental: bool = False,
    schedule_timestamp: Optional[str] = None,
) -> None

Modify a previously scheduled Barbara Core update — only valid while it is still "schedule" type and hasn't run yet.

cancel_barbara_core_update

cancel_barbara_core_update(node_id: str) -> None

get_docker_prune_info

get_docker_prune_info(node_id: str, prune_target: str) -> Dict[str, Any]

prune_target is one of "prunevolumes", "prunenetworks", "prunecontainers", "pruneimages" — note the prune prefix on every value; the bare noun ("volumes", ...) 404s. The response shape depends on the target, so it's returned as a raw dict rather than a dataclass.

prune_docker

prune_docker(node_id: str, prune_target: str) -> None

prune_target is one of "prunevolumes", "prunenetworks", "prunecontainers", "pruneimages" — same values as get_docker_prune_info.

prune_docker_all

prune_docker_all(node_id: str, *, force: bool = False) -> None

prune_docker_builder

prune_docker_builder(node_id: str) -> None

restart_docker_daemon

restart_docker_daemon(node_id: str) -> None

delete_asset

delete_asset(node_id: str, *, name: str, path: str) -> None

Academy: "Node Assets" (Advanced Actions popup) — a per-node file store for operational documentation (schemas, install photos, scripts, ...). Only delete is exposed by the public API; there is no list/upload/download endpoint, so a caller must already know an asset's name/path (as shown in Panel) to remove it here.

update_date

update_date(node_id: str) -> None

Sends an update-date request to the node. No corresponding Barbara Academy article found — undocumented action, exact product-facing meaning unconfirmed.

create_docker_volume

create_docker_volume(node_id: str, volume_name: str) -> None

volume_name is base64-encoded internally, per Barbara's convention. See list_docker_volumes/delete_docker_volume for how to find and remove it afterwards — the API doesn't echo an id back here.

list_docker_volumes

list_docker_volumes(node_id: str) -> List[Dict[str, Any]]

There is no dedicated list endpoint for node docker volumes — this fetches the node and decodes the volume list nested in its document (each entry has the _id that delete_docker_volume needs, plus a base64-encoded name).

delete_docker_volume

delete_docker_volume(node_id: str, volume_id: str) -> None

volume_id is the _id from list_docker_volumes() — not the volume name.

get_telemetry_latency

get_telemetry_latency(node_id: str) -> Dict[str, Any]

Returns the telemetryLatency object as a raw dict — it nests current, sent, and lastUpdate fields.

set_telemetry_latency

set_telemetry_latency(node_id: str, seconds: int) -> None

seconds must be at least 20, per the API's minimum.

get_last_telemetry

get_last_telemetry(node_id: str) -> Dict[str, Any]

Uses the /v2 endpoint (the /v1 one is deprecated for nodes on agent 1.9.5+). Returned as a raw dict — telemetry has many nested fields (disk, network, containers, ...) not worth turning into a dataclass here.

get_process_list

get_process_list(
    node_id: str,
    *,
    time: str,
    from_: str = '1970-01-01T00:00:00.000Z',
    to: Optional[str] = None,
) -> List[str]

time is "relative" or "absolute"; to is required when time="absolute". There is no /v2 equivalent of this endpoint yet, so it's used even though the API marks it deprecated for nodes on agent 1.9.5+.

AsyncNodesResource

AsyncNodesResource(client: AsyncBarbaraClient)

list

list(*, search: Optional[str] = None, size: Optional[int] = None) -> List[Node]

paginate

paginate(*, search: Optional[str] = None, size: int = 50, from_: int = 0) -> Page

get

get(node_id: str) -> Node

resolve

resolve(node_name: str) -> Node

delete

delete(node_id: str) -> None

add_node

add_node(
    node_names: List[str],
    assigned_names: List[str],
    tags: List[str],
    *,
    provisioned: bool = False,
    group: str = '',
    family_id: str = '',
    disk_overload: Optional[Dict[str, Any]] = None,
    gps: Optional[Dict[str, Any]] = None,
) -> None

get_name

get_name(node_id: str) -> str

update_name

update_name(node_id: str, name: str) -> None

add_tag

add_tag(node_id: str, tag: str) -> None

update_tags

update_tags(node_id: str, tags: List[str]) -> None

delete_tag

delete_tag(node_id: str, tag: str) -> None

list_by_tags

list_by_tags(tags: List[str]) -> List[Node]

Async counterpart of NodesResource.list_by_tags — see there for why this is a client-side filter over paginate().

update_safety_actions

update_safety_actions(
    node_id: str,
    *,
    trigger_threshold: float,
    stop_apps: bool = False,
    prune_all: bool = False,
    prune_images: bool = False,
    prune_containers: bool = False,
    prune_volumes: bool = False,
) -> None

get_alive

get_alive(node_id: str) -> bool

get_location

get_location(node_id: str) -> Dict[str, Any]

set_location

set_location(
    node_id: str,
    *,
    lat: float,
    lng: float,
    country: Optional[str] = None,
    city: Optional[str] = None,
    region: Optional[str] = None,
) -> None

delete_location

delete_location(node_id: str) -> None

list_groups

list_groups(node_id: str) -> List[Group]

list_global_secrets

list_global_secrets(node_id: str) -> List[GlobalSecret]

create_global_secrets

create_global_secrets(node_id: str, secrets: Dict[str, str]) -> None

delete_global_secret

delete_global_secret(node_id: str, secret_id: str) -> None

delete_all_global_secrets

delete_all_global_secrets(node_id: str) -> None

get_global_secret

get_global_secret(node_id: str, secret_id: str) -> GlobalSecret

get_global_config

get_global_config(node_id: str) -> Dict[str, Any]

set_global_config

set_global_config(
    node_id: str,
    *,
    config: Optional[Dict[str, Any]] = None,
    config_id: Optional[str] = None,
) -> None

list_docker_credentials

list_docker_credentials(node_id: str) -> List[DockerCredential]

get_docker_credential

get_docker_credential(node_id: str, credential_id: str) -> DockerCredential

create_docker_credentials

create_docker_credentials(node_id: str, credentials: List[Dict[str, str]]) -> None

delete_docker_credential

delete_docker_credential(node_id: str, credential_id: str) -> None

delete_all_docker_credentials

delete_all_docker_credentials(node_id: str) -> None

reboot

reboot(node_id: str, *, force: bool = False) -> None

poweroff

poweroff(node_id: str) -> None

provision

provision(node_id: str) -> None

deprovision

deprovision(node_id: str) -> None

brick

brick(node_id: str) -> None

update_barbara_core

update_barbara_core(
    node_id: str,
    update_type: str,
    *,
    incremental: bool = False,
    schedule_timestamp: Optional[str] = None,
) -> None

update_barbara_core_schedule

update_barbara_core_schedule(
    node_id: str,
    update_type: str,
    *,
    incremental: bool = False,
    schedule_timestamp: Optional[str] = None,
) -> None

cancel_barbara_core_update

cancel_barbara_core_update(node_id: str) -> None

get_docker_prune_info

get_docker_prune_info(node_id: str, prune_target: str) -> Dict[str, Any]

prune_docker

prune_docker(node_id: str, prune_target: str) -> None

prune_docker_all

prune_docker_all(node_id: str, *, force: bool = False) -> None

prune_docker_builder

prune_docker_builder(node_id: str) -> None

restart_docker_daemon

restart_docker_daemon(node_id: str) -> None

delete_asset

delete_asset(node_id: str, *, name: str, path: str) -> None

update_date

update_date(node_id: str) -> None

create_docker_volume

create_docker_volume(node_id: str, volume_name: str) -> None

list_docker_volumes

list_docker_volumes(node_id: str) -> List[Dict[str, Any]]

delete_docker_volume

delete_docker_volume(node_id: str, volume_id: str) -> None

get_telemetry_latency

get_telemetry_latency(node_id: str) -> Dict[str, Any]

set_telemetry_latency

set_telemetry_latency(node_id: str, seconds: int) -> None

get_last_telemetry

get_last_telemetry(node_id: str) -> Dict[str, Any]

get_process_list

get_process_list(
    node_id: str,
    *,
    time: str,
    from_: str = '1970-01-01T00:00:00.000Z',
    to: Optional[str] = None,
) -> List[str]

---

Signatures above are generated from barbara-api-sdk 0.5.0 docstrings. If a new SDK release changes one, this page needs a re-sync — the surrounding prose does not update itself.