API reference

The server exposes a REST API consumed by the desktop client. All endpoints return application/json. Errors share a single shape:

{ "error": "error_code", "message": "Human-readable description" }

Status	Meaning
400	Validation failure (response also includes an errors array)
401	Missing, invalid, or expired JWT
409	Sync conflict or quota violation
502	Upstream AI provider connection failure
503	AI proxy not configured
504	Upstream AI provider timeout

DTOs are defined in the Pia.Shared project (net10.0, no Windows dependency). Sync DTOs are prefixed with Sync, server entities with Server. Mapping between layers is explicit — no AutoMapper.

Auth endpoints

Method	Path	Auth	Rate	Body / Params
GET	/auth/login	—	auth	?provider=google|microsoft|entraid&redirect_uri=...
GET	/auth/callback	—	auth	OAuth implicit redirect
POST	/auth/refresh	—	auth	{ "refreshToken": "..." }
POST	/auth/logout	—	auth	{ "refreshToken": "..." }
GET	/auth/me	JWT	global	—

Login / refresh response:

{ "accessToken": "jwt...", "refreshToken": "opaque-string", "expiresIn": 900 }

Access tokens are JWT (HS256, issuer pia-server, audience pia-client) and live 15 minutes. Refresh tokens are opaque strings stored hashed; rotation is mandatory on every refresh, with a 10-token-per-user cap.

Sync endpoints

Method	Path	Auth	Rate	Purpose
GET	/api/sync/pull?since={ISO8601}	JWT	sync	Incremental pull
POST	/api/sync/push	JWT	sync	Push client changes
GET	/api/sync/status	JWT	global	Sync status
GET	/api/sync/events	JWT	global	Audit log
GET	/api/sync/quota	JWT	global	Usage stats

Push request (SyncPushRequest):

{
  "templates": [...],
  "providers": [...],
  "sessions":  [...],
  "memories":  [...],
  "todos":     [...],
  "settings":  { ... }
}

Push response (SyncPushResponse): server-assigned IDs, conflict list, resolution instructions. Conflicts use SyncConflict with strategy last-write-wins (default) or server-wins.

See the Sync protocol page for the full request lifecycle.

AI proxy endpoints

Method	Path	Auth	Rate	Purpose
GET	/api/ai/status	—	global	Proxy availability
GET	/api/ai/templates	—	global	Built-in template list
POST	/api/ai/optimize	optional	ai	Text optimization

Optimize request:

{ "text": "...", "templateId": "...", "providerId": "..." }

text is capped at 10,000 characters. Input is sanitized server-side before forwarding to the upstream provider. The response either streams or returns { "result": "..." }.

The X-Pia-Mode header (values: optimize, assistant, research) selects which configured upstream provider to use. Per-mode overrides are documented under Configuration.

E2EE device endpoints

Method	Path	Auth	Rate	Purpose
POST	/api/e2ee/devices/register	JWT	global	Register device as Pending
GET	/api/e2ee/devices	JWT	global	List user’s devices
POST	/api/e2ee/devices/approve	JWT	global	Approve a pending device (wrap UMK for it)
POST	/api/e2ee/devices/revoke	JWT	global	Revoke a device
GET	/api/e2ee/devices/wrapped-umk/{deviceId}	JWT	global	Fetch wrapped UMK for a device
PUT	/api/e2ee/devices/wrapped-umk	JWT	global	Store wrapped UMK for a device

E2EE recovery endpoints

Method	Path	Auth	Rate	Purpose
POST	/api/e2ee/recovery/wrapped-umk	JWT	global	Store recovery-wrapped UMK
GET	/api/e2ee/recovery/wrapped-umk	JWT	global	Retrieve recovery-wrapped UMK
POST	/api/e2ee/recovery/activate	JWT	global	Activate device via recovery code

Shared DTOs

Located in Pia.Shared:

• Sync — SyncPullResponse, SyncPushRequest, SyncPushResponse, SyncConflict, SyncTemplate, SyncProvider, SyncSession, SyncMemory, SyncTodo, SyncSettings.
• E2EE — DeviceStatus (enum), DeviceInfo, DeviceRegistrationRequest/Response, DeviceApprovalRequest, WrappedUmkBlob, RecoveryWrappedUmkBlob, RecoveryActivationRequest.
• Models — BuiltInTemplate.

Serialization uses System.Text.Json with default options.