> For the complete documentation index, see [llms.txt](https://docs.vex-nx.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vex-nx.com/developers/rest-api-overview.md).

# REST API overview

![REST API overview (diagram)](https://1807546539-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhgHCHWL3861o2DBW53aA%2Fuploads%2FkTxRLK1Zihq2EzdTJ8Ii%2Fve20261112v5-diagram-api.png?alt=media)

## Goal

Authenticate and call the VEX-NX HTTP API from scripts or AI tools.

## Base URL

```
http://<appliance-ip>/api/v1
```

or `https://<appliance-ip>/api/v1` when TLS is enabled on the appliance.

Replace `<appliance-ip>` with your management address. Do not commit real tokens or passwords into repos or docs.

## Authentication

1. Log in and receive a JWT:

```http
POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "<your-password>"
}
```

2. Send the token on later calls:

```http
Authorization: Bearer <token>
```

Roles include `admin`, `editor`, and `user`. Lab ownership rules still apply.

First-login may require a password change on new appliances - complete that in the UI before automation.

## Common resource groups

| Area               | Examples                                                        |
| ------------------ | --------------------------------------------------------------- |
| Health             | `GET /api/v1/health`                                            |
| Labs               | `GET/POST /api/v1/labs`, `GET /api/v1/labs/{labId}`             |
| Lab power          | `POST /api/v1/labs/{labId}/start`, `.../stop`, `.../wipe`       |
| Nodes              | `POST /api/v1/labs/{labId}/nodes`, start/stop/wipe per node     |
| Images / templates | `GET /api/v1/images`, `GET /api/v1/templates`                   |
| Consoles           | HTML5 WS paths; external mint under `.../console-external`      |
| Assist             | `POST /api/v1/assist/agent` (NDJSON events); lab assist helpers |
| MCP tools          | `GET /api/v1/mcp/tools`, `POST /api/v1/mcp/call`                |
| Captures           | `/api/v1/captures*`                                             |

Exact paths evolve with releases. Prefer the OpenAPI reference checked into this docs set for a structured list.

## Minimal examples

### Health

```bash
curl -fsS "http://<appliance-ip>/api/v1/health"
```

### Login + list labs

```bash
TOKEN=$(curl -fsS -X POST "http://<appliance-ip>/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"<your-password>"}' \
  | python -c "import sys,json; print(json.load(sys.stdin)['token'])")

curl -fsS "http://<appliance-ip>/api/v1/labs" \
  -H "Authorization: Bearer $TOKEN"
```

### Start a lab

```bash
curl -fsS -X POST "http://<appliance-ip>/api/v1/labs/<labId>/start" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Editions

Assist, MCP, capture, and import endpoints work on both editions (Student and Enterprise). Enterprise raises the lab / node / user limits that some create endpoints enforce, and classroom timer and LDAP endpoints require Enterprise. See [Features](/getting-started/features.md).

## Related

* OpenAPI reference
* MCP and AI tools
* [Using Assist](/assist/using-assist.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.vex-nx.com/developers/rest-api-overview.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.