Verified by the sovseal team
API Reference Overview
HTTP surface exposed by the sovseal replication endpoint (Platform & self-hosted).
Zero-Knowledge Design
The sovseal replication API is server-blind by design. Plaintext memories are encrypted client-side using AES-256-GCM before transmission. The server only stores, indexes, and replication-syncs opaque ciphertext envelopes.
Base URLs
Depending on whether you are using the managed sovseal cloud or self-hosting, all HTTP requests target one of the following endpoints:
| Environment | Base URL |
|---|---|
| sovseal Platform | https://ksrlmubaxzwufziwarps.supabase.co/functions/v1/v2-agent-state |
| Self-Hosted | http://localhost:54321/functions/v1/v2-agent-state (default local port) |
Endpoint Catalog
The API surface is divided into five core sections mapping directly to the underlying edge function handlers:
1. Core Operations
POST /snapshot— Create a new state checkpoint (differential or genesis).GET /snapshot/:agent_id/latest— Restore the latest confirmed snapshot.GET /snapshot/:agent_id/:sequence— Restore a snapshot at a specific sequence number.GET /snapshot/:agent_id/lineage— Walk the parent lineage chain backward.
2. Replication Log
POST /replicate— Upload one or more ciphertext chunk diffs (write-behind synchronization).GET /head— Retrieve latest sequence number and Merkle root.GET /replay— Replay replication log entries starting from sequence $N$.
3. Server Aggregates
GET /metadata— Retrieve server-knowable metadata (envelope counts, total bytes, device counts, and last sync timestamp).GET /envelopes— Retrieve paginated list of encrypted envelopes with split IVs.
4. Dashboard Services (Session-JWT Authed)
POST /api-keys— Issue a new API key (sov_live_...).GET /api-keys— List all active and revoked API keys.DELETE /api-keys/:id— Revoke an API key.GET /settings— Retrieve user dashboard preferences.PUT /settings— Persist changes to user preferences (opt-in telemetry, project name).POST /telemetry— Submit aggregate-only telemetry reports.POST /billing/create-checkout— Create a checkout session with Polar.POST /billing/customer-portal— Retrieve a Polar customer billing portal session redirect.GET /billing/subscription— Fetch the user's active subscription plan details.GET /billing/usage— Fetch aggregated usage counters.
5. Team Collaboration (Full ZK)
POST /teams— Create a team and issue the initial owner key grant.POST /teams/:id/grants— Issue key grants wrapping the team's data encryption key (DEK) to new members.GET /teams/:id/grant— Fetch the member's own wrapped DEK.POST /teams/:id/rotate— Revoke members, rotate the team's DEK, and re-wrap to remaining active members.POST /teams/:id/memories— Append encrypted team memories.GET /teams/:id/memories— Retrieve team memory ciphertext history.POST /teams/:id/subkeys— Issue revocable sub-keys bound to team member grants.GET /teams/:id/sync-log— Get audit/sync log metrics.GET /teams/:id/members— List membership roster status and roles.