Nanami DocsGuide
Search docsFilter pages by title

Endpoint reference

This page summarizes the current API groups under /api/v1.

Conventions

  • Base path: /api/v1
  • JSON request/response payloads
  • Standard HTTP semantics (2xx, 4xx, 5xx)
  • Auth required for protected routes

Core endpoint groups

| Group | Purpose | | --- | --- | | /auth/* | login, refresh, logout, password reset, OAuth, invite acceptance | | /client/* | managed-client onboarding flow for CLI (devices, config, heartbeat) | | /users/* | user lifecycle, group membership, access views | | /groups/* | group lifecycle | | /networks/* | network lifecycle, routing policy CRUD, DNS record CRUD | | /routing-policies/* | routing policy detail update/delete | | /nodes/* | node lifecycle and WireGuard config output | | /devices/* | device lifecycle and routing preferences | | /dns/* | DNS records API (/dns/records, /dns/records/:id) | | /regions/* | region inventory | | /gateways/* | gateway runtime inventory | | /agents/* | gateway-manager and gateway-daemon agent inventory | | /tunnels/* | tunnel list and runtime counters | | /notifications/* | notification settings | | /admin/settings | platform-level settings |

Managed Client canonical routes

  • Login: POST /api/v1/auth/login
  • Enroll: POST /api/v1/client/devices
  • Refresh config: POST /api/v1/client/devices/:id/config
  • Heartbeat: POST /api/v1/client/devices/:id/heartbeat

Managed-client validation responses use:

  • 422 with VALIDATION_ERROR + fields[] for schema/binding validation
  • 400 with { "error": { "code": "validation_error", "message": "<reason>" } } for domain validation
  • 401/403/404 using the same error envelope

Routing Policies MVP routes

  • GET /api/v1/networks/:id/routing-policies
  • POST /api/v1/networks/:id/routing-policies
  • GET /api/v1/routing-policies/:id
  • PUT /api/v1/routing-policies/:id
  • DELETE /api/v1/routing-policies/:id

ViaGateway policies validate:

  • ordered gatewayPath,
  • gateways must exist and have Gateway role in the target network,
  • max hops via ROUTING_POLICY_MAX_HOPS (default 3).

Generated WireGuard configs now include routingIntent[] as desired-state export.

DNS MVP runtime routes

  • GET /api/v1/networks/:id/dns/records
  • POST /api/v1/networks/:id/dns/records
  • PUT /api/v1/dns/records/:id
  • DELETE /api/v1/dns/records/:id
  • GET /api/v1/networks/:id/dns/corefile (deterministic CoreDNS artifact)
  • GET /api/v1/networks/:id/runtime-status (routing + DNS desired/applied status)

Example: create network

bash
curl -X POST http://localhost:8080/api/v1/networks \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"groupId":"<group-id>","name":"prod-eu","cidr":"10.42.0.0/16"}'

Example: create routing policy

bash
curl -X POST http://localhost:8080/api/v1/networks/<network-id>/routing-policies \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"corp-egress","type":"via_gateway","destinationCidr":"10.0.0.0/24","gatewayPath":["<gateway-node-id>"]}'

Example: create DNS record

bash
curl -X POST http://localhost:8080/api/v1/networks/<network-id>/dns/records \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"api","type":"A","value":"100.64.0.10","ttl":60}'

Current docs scope and roadmap

  • This page is intentionally high-level.
  • Generated OpenAPI docs and SDK-focused references are planned as documentation maturity work.
Edit this page