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 shelling out to the CLI.

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

Endpoints

  • GET /healthz – health check.

  • GET /templates?dir=<path> – list YAML templates 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 – netlab status output.

Actions

action maps to CLI behaviors:

  • up

  • create

  • down

  • collect

  • status

The API runs the same Python CLI modules used by netlab, so behavior and output are consistent with the CLI.

Authentication

If NETLAB_API_USER and NETLAB_API_PASSWORD (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 (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.