roof/pic
1
0
Fork 0
Code Issues Pull Requests Actions Wiki Activity
Page: Dev – API Reference
Pages
ADR – 001 Store Images Are Signed and Verified by Cells ADR – 002 Named Connection Instances for Connectivity ADR – 003 All Optional Functionality Ships as Store Services Admin – Back Up and Restore Admin – Configure Connectivity Admin – Configure Domains and TLS Admin – Install and First Run Admin – Logging and Audit Admin – Manage Peers Admin – Manage Services Admin – Monitor and Troubleshoot Admin – Overview Archive – ADR 004 The Wiki Is the Single Documentation Source Archive – User Guide Dev – API Reference Dev – Architecture Dev – Build a Store Service Dev – Install Internals Dev – Overview Dev – Service Manifest Reference Dev – Testing Home Meta – Glossary Meta – Template ADR Meta – Template Runbook User – Connect to the VPN User – FAQ User – Start Here User – Troubleshooting User – Use Your Services
Clone
Dev – API Reference
Dmitrii Iurco edited this page 2026-06-11 15:39:28 -04:00
Table of Contents

Status: Active | Owner: @roof | Applies to: main (2026-06) | Updated: 2026-06-11

Dev – API Reference

Base URL: http://localhost:3000 (bound to 127.0.0.1; always access through Caddy in production)

All /api/* endpoints require an authenticated session after setup is complete. The only always-public endpoint is GET /health.

Authentication

Session-based. Two roles:

Role Access
admin All /api/* except /api/peer/*
peer /api/peer/* only

Login flow

POST /api/auth/login
{"username": "admin", "password": "<your-password>"}

Returns a session cookie. All subsequent requests include the cookie.

CSRF protection

All POST, PUT, DELETE, PATCH on /api/* (except /api/auth/* and /api/setup/*) require the X-CSRF-Token header.

Fetch the token:

GET /api/auth/csrf-token

Include it in every mutating request:

X-CSRF-Token: <token>

Auth endpoints

Method Path Description
POST /api/auth/login Create session
POST /api/auth/logout Destroy session
GET /api/auth/me Current user info
GET /api/auth/csrf-token Get CSRF token
POST /api/auth/change-password Change own password
POST /api/auth/admin/reset-password Admin: reset another user's password
GET /api/auth/users Admin: list users

Setup

Method Path Description
GET /api/setup/status Setup complete flag + current step
GET /api/setup/step Current wizard step data
POST /api/setup/step Submit current step
POST /api/setup/complete Finalize setup

Core

Method Path Description
GET /health Always-public health check
GET /api/status All-service status summary
GET /api/config Full cell config
PUT /api/config Update cell config
GET /api/health/history Recent health check history

WireGuard and peers

Method Path Description
GET /api/wireguard/status WireGuard running state and stats
GET /api/peers List all peers
POST /api/peers Add a peer
GET /api/peers/<name> Get peer details
PUT /api/peers/<name> Update peer
DELETE /api/peers/<name> Remove peer and their service accounts
GET /api/peers/<name>/qr Peer config as QR code
GET /api/peers/<name>/service-credentials Filled connection info for all services

Network services

DNS overview, NTP status, network connectivity tests, split-horizon zone reload, DDNS force-refresh.

Relevant paths: /api/dns/*, /api/ntp/*, /api/network/*.

Services and store

Method Path Description
GET /api/services/active Installed services with name, subdomain, capabilities
GET /api/store Full catalog from pic-services index
POST /api/store/install Install a service by ID
POST /api/store/remove Remove an installed service
GET /api/services/catalog/<id>/status Container status for a service
POST /api/services/catalog/<id>/restart Restart service containers
GET /api/services/catalog/<id>/accounts List provisioned accounts
POST /api/services/catalog/<id>/accounts Provision peer account
DELETE /api/services/catalog/<id>/accounts/<username> Deprovision peer account
GET /api/services/catalog/<id>/accounts/<username>/credentials Get stored credentials

Connectivity (v2)

Method Path Description
GET /api/connectivity/connections List all connection instances (with status)
POST /api/connectivity/connections Create a named connection instance
PUT /api/connectivity/connections/<id> Update connection name/config/secrets
DELETE /api/connectivity/connections/<id> Delete connection (409 if in use)
GET /api/connectivity/connections/<id>/health On-demand health probe
PUT /api/connectivity/peers/<peer>/exit Assign peer to a connection
GET /api/connectivity/peers List peer exit assignments
PUT /api/connectivity/peers/<peer>/failopen Set/clear per-peer fail-open override
GET /api/connectivity/status Connectivity overall status
GET /api/connectivity/exits Legacy: configured exits summary

POST /api/connectivity/connections body:

{
  "type": "wireguard_ext",
  "name": "My VPN",
  "config": {},
  "secrets": {"conf": "<wireguard-conf-content>"}
}

Secrets are stored in the vault. They are never echoed in responses.

Audit log

Method Path Description
GET /api/audit Query audit entries (admin only)
GET /api/audit/export?format=csv Export as CSV
GET /api/audit/verify Verify hash chain integrity

Query parameters for GET /api/audit: actor, action, target_type, target_id, result, since, until, limit, offset.

Logs

Method Path Description
GET /api/logs Recent log lines (query: service, lines)
GET /api/logs/verbosity Current Python and container log levels
PUT /api/logs/verbosity Update log levels
GET /api/logs/search Search logs (query: q, service)

Vault

Certificate issue/revoke, CA certificate download, trust key management, Age public key: /api/vault/*.

Containers

List, start, stop, inspect containers; manage images and volumes: /api/containers/*.

Cell network

List connected cells, add/remove cell links, peer-sync: /api/cells/*.

Cell-to-cell peer-sync endpoints (/api/cells/peer-sync/*) authenticate via source IP and WireGuard public key — not session cookies.

Email, calendar, files

These endpoints exist only when the respective service is installed. Non-status routes return HTTP 404 when the service is not installed.

  • /api/email/* — mailbox and account management
  • /api/calendar/* — user/calendar/contacts management
  • /api/files/* — WebDAV user and file management

Routing and firewall

NAT rules, per-peer routing policy, exit configuration: /api/routing/*.

TLS

GET /api/caddy/cert-status     TLS certificate expiry and domain
POST /api/caddy/cert-renew     Force certificate renewal

Personal Internet Cell

Home

New here?

User – Start Here User – FAQ

Users

User – Connect to the VPN User – Use Your Services User – Troubleshooting

Admins

Admin – Overview Admin – Install and First Run Admin – Configure Domains and TLS Admin – Manage Services Admin – Configure Connectivity Admin – Manage Peers Admin – Back Up and Restore Admin – Logging and Audit Admin – Monitor and Troubleshoot

Developers

Dev – Overview Dev – Architecture Dev – Build a Store Service Dev – Service Manifest Reference Dev – API Reference Dev – Testing Dev – Install Internals

Decisions (ADRs)

ADR – 001 Store Images Are Signed and Verified by Cells ADR – 002 Named Connection Instances for Connectivity ADR – 003 All Optional Functionality Ships as Store Services

Meta

Meta – Glossary Meta – Template Runbook Meta – Template ADR

Archive

Archive – User Guide Archive – ADR 004 The Wiki Is the Single Documentation Source