API Reference

API Reference

REST API endpoints with curl examples. Enable Swagger UI at /api/docs/ with NIDUS_ENABLE_DOCS=true.

Authentication

Login

POST /api/auth/login 
curl -X POST http://localhost:3777/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"yourpassword"}'

Response:

{"message":"login successful","user":{"id":1,"username":"admin","role":"admin"}}

The JWT token is set as a cookie (nidus_token). For curl, pass it with -b:

# Save cookie on login
curl -c cookies.txt -X POST http://localhost:3777/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"yourpassword"}'

# Use cookie for authenticated requests
curl -b cookies.txt http://localhost:3777/api/categories

Or use the Authorization header:

curl http://localhost:3777/api/categories \
  -H "Authorization: Bearer <your-jwt-token>"

Check setup status

GET /api/auth/status 
curl http://localhost:3777/api/auth/status

Categories

List categories

GET /api/categories 
curl -b cookies.txt http://localhost:3777/api/categories

Create a category

POST /api/categories 
curl -b cookies.txt -X POST http://localhost:3777/api/categories \
  -H "Content-Type: application/json" \
  -d '{"name":"Media","icon":"tv"}'

Widgets

List widgets in a category

GET /api/categories/:id/widgets 
curl -b cookies.txt http://localhost:3777/api/categories/1/widgets

Create a widget

POST /api/categories/:id/widgets 
curl -b cookies.txt -X POST http://localhost:3777/api/categories/1/widgets \
  -H "Content-Type: application/json" \
  -d '{"type":"docker","title":"My Docker","config":"{}","pos_x":0,"pos_y":0,"width":4,"height":0}'

Services

List configured services

GET /api/services 
curl -b cookies.txt http://localhost:3777/api/services

Configure a service

PUT /api/services/:type 
curl -b cookies.txt -X PUT http://localhost:3777/api/services/portainer \
  -H "Content-Type: application/json" \
  -d '{"name":"Portainer","url":"https://portainer.local:9443","credentials":"{\"api_key\":\"your-api-key\"}"}'

Test service connectivity

POST /api/services/:type/test 
curl -b cookies.txt -X POST http://localhost:3777/api/services/portainer/test

Docker

List environments

GET /api/docker/environments 
curl -b cookies.txt http://localhost:3777/api/docker/environments

List containers

GET /api/docker/environments/:id/containers 
curl -b cookies.txt http://localhost:3777/api/docker/environments/1/containers

Container action (start/stop/restart)

POST /api/docker/environments/:id/containers/:containerId/:action 
curl -b cookies.txt -X POST http://localhost:3777/api/docker/environments/1/containers/abc123/restart

Settings

Get current settings

GET /api/settings 
curl -b cookies.txt http://localhost:3777/api/settings

Update settings

PUT /api/settings 
curl -b cookies.txt -X PUT http://localhost:3777/api/settings \
  -H "Content-Type: application/json" \
  -d '{"theme":"nord","language":"en","refresh_interval":15}'

Config Export/Import

Export as YAML

GET /api/config/yaml 
curl -b cookies.txt http://localhost:3777/api/config/yaml -o nidus-config.yaml

Import YAML

POST /api/config/yaml 
curl -b cookies.txt -X POST http://localhost:3777/api/config/yaml \
  -H "Content-Type: application/json" \
  --data-binary @nidus-config.yaml