(netlab-api)=
# 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.

```text
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.