netlab API Server

The netlab api command starts a lightweight HTTP server that wraps common CLI actions. It is intended for automation systems that need to invoke netlab operations without executing CLI commands.

netlab api [--bind <addr>] [--port <port>] [--auth-user <user>] [--auth-password <password>]
           [--tls-cert <path>] [--tls-key <path>]

The HTTP(S) server is started on the address specified in the --bind parameter or NETLAB_API_BIND environment variable. If you start the API server in an SSH session, the server uses the SSH_CONNECTION  environment variable to find the local IP address to bind to. Lacking all other options, the API server is started on the loopback interface.

Endpoints

  • GET /healthz – health check.

  • GET /templates?dir=<path> – list YAML templates (topologies) in a directory.

  • POST /jobs – start a job. Body is JSON with fields such as action, workdir, workspaceRoot, topologyPath, or topologyUrl.

  • GET /jobs – list jobs.

  • GET /jobs/{id} – job details.

  • GET /jobs/{id}/log – job log output.

  • POST /jobs/{id}/cancel – mark a job as canceled.

  • GET /status[?output=text] – the overall status of netlab lab instances on the server as generated by netlab status –all.

  • GET /status/{instance}[?output=text] – netlab status output of the selected instance as generated by netlab status –instance instance.

Tip

You can use the ?output=text query string or set the NETLAB_API_STATUS_OUTPUT environment variable to text to get the status results in the format printed by the netlab status command. Otherwise, the lab status is returned as a JSON document as generated by the ‌netlab status –format json command.

Actions

action maps to CLI behaviors:

  • up

  • create

  • down

  • collect

  • status

The API uses the same Python CLI modules as netlab, so its behavior and output are consistent with the CLI commands.

Authentication

If NETLAB_API_USER and NETLAB_API_PASSWORD environment variables (or the --auth-user and --auth-password flags) are set, the server requires HTTP Basic Auth on all endpoints.

TLS

If NETLAB_API_TLS_CERT and NETLAB_API_TLS_KEY environment variables (or the --tls-cert and --tls-key flags) are set, the server enables HTTPS using those files.

Working Directory

The API uses the netlab working directory model:

  • If workdir is set, it is used as the working directory.

  • Else, if workspaceRoot is set, it becomes the working directory.

  • Otherwise, the server’s current working directory is used.