API Reference

Sherpa provides a unified API accessible via three transports. The API specification is auto-generated from the codebase and served as a live OpenAPI 3.1 document.

Swagger UI

Sherpa ships with a built-in Swagger UI for interactive API exploration. Access it from any running Sherpa server at:

https://<server>:3030/api/docs

The Swagger UI lets you browse all available operations, inspect request/response schemas, and test endpoints directly from the browser. It is served from the Sherpa server itself, so it always reflects the exact API version running on that server.

OpenAPI Specification

The raw OpenAPI 3.1 JSON specification is available at:

GET https://<server>:3030/api/v1/openapi.json

This can be imported into tools like Postman, Insomnia, or any OpenAPI-compatible client for generating API bindings or documentation.

Transports

REST API

Standard HTTP endpoints served on the configured ws_port (default: 3030). Supports JSON request/response bodies and Server-Sent Events (SSE) for streaming operations.

WebSocket RPC

JSON-RPC 2.0 over WebSocket at wss://<server>:3030/ws. This is the transport used by the sherpa CLI.

CLI

The sherpa command-line tool wraps the WebSocket RPC transport. See the Command Reference for all available commands.

Authentication

All authenticated endpoints support two methods:

• Bearer Token: Authorization: Bearer <jwt> header
• Cookie: sherpa_token cookie (used by the web UI)

Obtain a token via the login endpoint:

# CLI
sherpa login

# REST
curl -X POST https://<server>:3030/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}'

Operation Categories

Category	Operations	Auth Level
Auth	Login, validate token	None
Lab	Create, destroy, inspect, down, resume	Authenticated
Node	Redeploy	Authenticated
Link	Update impairment	Authenticated
Image	List, show, import, pull, delete, set-default, scan, download, upload	Admin
User	Create, list, delete, change password, info	Admin
Admin	Force clean lab	Admin