super-productivity/docs/wiki/3.01-API.md

APIs

Super Productivity exposes two API systems: the Sync Server REST API (for data synchronization) and the Plugin API (for extending the app). This reference summarizes both; full request/response schemas and examples live in the repository (Sync Server: packages/super-sync-server/; Plugin API: packages/plugin-api/ and docs/plugin-development.md).

1. Sync Server REST API

The Sync Server is a custom, operation-based synchronization service (event-sourcing style). It is not WebDAV. It is intended for use with the built-in SuperSync sync provider. See 2.08-Choose-Sync-Backend and 2.09-Configure-Sync-Backend for user-facing sync options.

Authentication and Authorization

All sync endpoints require JWT Bearer authentication: Authorization: Bearer <token>.

• Token expiry: 7 days.
• Environment: Server requires JWT_SECRET (minimum 32 characters).
• Token contents: userId, email, tokenVersion (for invalidation).
• Invalid or missing token returns 401.

Authentication Endpoints

Traditional:

• POST /api/register — User registration (email verification required).
• POST /api/login — Password login.
• POST /api/verify-email — Email verification.
• POST /api/replace-token — Replace compromised JWT (requires current auth).

Passkey (WebAuthn):

• POST /api/register/passkey/options — Registration options.
• POST /api/register/passkey/verify — Verify registration.
• POST /api/login/passkey/options — Authentication options.
• POST /api/login/passkey/verify — Verify authentication.
• POST /api/recover/passkey — Request passkey recovery (e.g. magic link).
• POST /api/recover/passkey/options — Recovery registration options.
• POST /api/recover/passkey/complete — Complete recovery.

Magic link:

• POST /api/login/magic-link — Request magic link email.
• POST /api/login/magic-link/verify — Verify magic link token.

Account:

• DELETE /api/account — Delete user and all data (requires auth).

Synchronization Endpoints

All require authentication.

Operations:

• POST /api/sync/ops — Upload operations (incremental). Request: ops[], clientId, optional lastKnownServerSeq, optional requestId (deduplication).
• GET /api/sync/ops?sinceSeq={seq}&limit={limit}&excludeClient={clientId} — Download operations. Query: sinceSeq (required), limit (default 500, max 1000), excludeClient (optional).

Snapshots:

• GET /api/sync/snapshot — Get full state snapshot.
• POST /api/sync/snapshot — Upload full state (backup/repair/migration). Body limit 30 MB (compressed).

Status and maintenance:

• GET /api/sync/status — Sync status and storage info.
• DELETE /api/sync/data — Delete all sync data for the user (e.g. encryption password change).
• GET /api/sync/restore-points?limit={limit} — List restore points (limit 1–100).
• GET /api/sync/restore/{serverSeq} — Get state snapshot at a specific sequence.

Health:

• GET /health — Database connectivity check (no auth). Returns 200 with { status: 'ok', db: 'connected' } or 503 on failure.

Request/Response Overview

• Upload ops: Body is an array of operations; each has id, clientId, actionType, opType, entityType, entityId/entityIds, payload, vectorClock, timestamp, schemaVersion, optional isPayloadEncrypted. Response: results[] (per-op accepted/rejected + serverSeq), optional newOps, latestSeq, optional hasMorePiggyback, optional deduplicated.
• Download ops: Response: ops, hasMore, latestSeq, optional gapDetected, optional latestSnapshotSeq, optional snapshotVectorClock, serverTime.
• Snapshot: Response: state, serverSeq, generatedAt. Upload snapshot body: state, clientId, reason, vectorClock, schemaVersion, optional isPayloadEncrypted.
• Status: Response: latestSeq, devicesOnline, optional snapshotAge, storageUsedBytes, storageQuotaBytes.

Exact schemas (Zod on server, TypeScript types in repo) are in packages/super-sync-server/src/sync/sync.types.ts and sync.routes.ts.

Error Codes

Structured error codes (for client handling) include: VALIDATION_FAILED, INVALID_OP_ID, INVALID_OP_TYPE, INVALID_ENTITY_TYPE, INVALID_ENTITY_ID, INVALID_PAYLOAD, PAYLOAD_TOO_LARGE, INVALID_VECTOR_CLOCK, INVALID_CLIENT_ID, CONFLICT_CONCURRENT, CONFLICT_STALE, DUPLICATE_OPERATION, RATE_LIMITED, STORAGE_QUOTA_EXCEEDED, ENCRYPTED_OPS_NOT_SUPPORTED, SYNC_IMPORT_EXISTS, INTERNAL_ERROR. Defined in sync.types.ts (SYNC_ERROR_CODES).

Rate Limits (per endpoint)

• Email verification: 20 / 15 min.
• Token replacement: 5 / 15 min.
• Account deletion: 3 / 15 min.
• Passkey registration: 10 / 15 min.
• Passkey login: 20 / 15 min.
• Passkey recovery (request/options/complete): 5–10 / 15 min.
• Magic link request: 5 / 15 min; verify: 10 / 15 min.
• Upload ops: 100 / 1 min.
• Download ops: 200 / 1 min.
• Snapshot (GET): 10 / 5 min.

Storage Quotas (Sync Server)

• Per user: Default 100 MB. Enforced before accepting uploads; automatic cleanup (restore points and old operations) when over quota.
• Upload limits: Max payload 20 MB; max operations per upload 100. Compressed ops body: 10 MB; compressed snapshot: 30 MB; decompressed cap (zip-bomb protection): 100 MB.

Compression

• Request: Gzip via Content-Encoding: gzip. Android can send base64-encoded gzip with Content-Transfer-Encoding: base64.
• Response: Server may send compressed responses where configured.

CORS

Configurable via environment/config. Typical allowed headers include Authorization, Content-Type, Content-Encoding, X-Expected-Rev, X-Force-Overwrite, X-Requested-With. Credentials supported.

Data Retention

Operations, devices, and related validation data are retained for 45 days. Older data is purged.

Request Deduplication

Upload ops accepts optional requestId. Repeated requests with the same requestId receive cached results (and fresh piggybacked ops if applicable), so clients can retry safely without duplicating operations.

End-to-End Encryption

Payloads can be encrypted client-side; server stores them as opaque blobs. Restore-at-sequence is not supported when operations are encrypted (ENCRYPTED_OPS_NOT_SUPPORTED).

---

2. Plugin API

The Plugin API is exposed to plugins via a global PluginAPI object. Plugins run in a sandboxed environment (VM or iframe). See 3.05-Web-App-vs-Desktop for web limitations (e.g. Node-only plugins disabled, iframe API restrictions). Full types and the development guide: packages/plugin-api/src/types.ts, docs/plugin-development.md.

Plugin API Categories

Data — Tasks:

• getTasks(), getArchivedTasks(), getCurrentContextTasks() — Read tasks.
• addTask(taskData), updateTask(taskId, updates), deleteTask(taskId) — Create/update/delete.
• batchUpdateForProject(request) — Batch create/update/delete/reorder for a project.
• reorderTasks(taskIds, contextId, contextType) — Reorder tasks.

Data — Projects:

• getAllProjects(), addProject(projectData), updateProject(projectId, updates).

Data — Tags:

• getAllTags(), addTag(tagData), updateTag(tagId, updates).

Data — Simple counters:

• setCounter(id, value), getCounter(id), incrementCounter(id, incrementBy), decrementCounter(id, decrementBy), deleteCounter(id), getAllCounters().

UI:

• showSnack(snackCfg), notify(notifyCfg) — Notifications.
• openDialog(dialogCfg), showIndexHtmlAsView() — Dialogs and plugin UI.

Registration (main plugin context only; not in iframe):

• registerHeaderButton(config), registerMenuEntry(config), registerShortcut(config), registerSidePanelButton(config), registerHook(hook, handler).

Persistence:

• persistDataSynced(dataStr), loadSyncedData(), getConfig() — Plugin-specific storage and config.

Advanced:

• executeNodeScript(request) — Run Node.js scripts (Electron only, nodeExecution permission and user consent).
• dispatchAction(action) — Dispatch NgRx actions (allowed subset).
• downloadFile(filename, data), isWindowFocused(), onWindowFocusChange(handler).

Hooks (Events)

Plugins can register handlers for: taskCreated, taskComplete, taskUpdate, taskDelete, currentTaskChange, finishDay, languageChange, persistedDataUpdate, action, anyTaskUpdate, projectListUpdate. Payload types are defined in plugin-api types (HookPayloadMap).

Plugin Data Types

Core types (Task, Project, Tag, ProjectFolder, etc.) and batch types (BatchUpdateRequest, BatchUpdateResult, BatchOperation, etc.) are in packages/plugin-api/src/types.ts.

Plugin Manifest

Plugins require manifest.json: name, id, manifestVersion, version, minSupVersion, optional description, hooks, permissions, optional iFrame, isSkipMenuEntry, type, assets, icon, nodeScriptConfig, sidePanel, jsonSchemaCfg. See PluginManifest in the repo.

Plugin Permissions

• nodeExecution: Required for executeNodeScript() (Electron only; user consent). See 3.05-Web-App-vs-Desktop and 3.06-User-Data for file-system and desktop-only behavior.
• Other permissions may gate specific API methods; see the plugin development guide.

Iframe Restrictions

When a plugin uses an iframe UI, the following are not available: registerHeaderButton, registerMenuEntry, registerSidePanelButton, registerShortcut, registerHook, execNodeScript. Iframe content is subject to CSP (e.g. no external scripts; same-origin or inlined only).

---

3. Versioning and Compatibility

Schema Versioning (Sync)

• Current schema version: 1 (shared schema in packages/shared-schema).
• Minimum supported: 1.
• Max version skip: 3 (if remote data is more than 3 versions ahead, client should update).
• Operations and snapshots carry schemaVersion; server validates and may reject unsupported versions.

Vector Clocks

Sync uses vector clocks for conflict resolution. Server validates/sanitizes clocks: max 100 entries; keys max 255 chars; values 0–10,000,000. Invalid entries are stripped.

API Validation (Sync Server)

• Operation IDs: 1–255 characters. Client IDs: alphanumeric, underscore, hyphen; max 255.
• Entity types: 1–255 characters. Schema version: 1–100.
• Payload validation by op type (CRT, UPD, DEL, MOV, BATCH, SYNC_IMPORT, etc.); see validatePayload in sync.types.ts.

---

Notes

• Sync Server: Production-oriented (JWT, rate limiting, CORS, Helmet). Multi-instance deployment has limitations (e.g. passkey challenge storage in memory; snapshot generation locks); single-instance is the typical deployment.
• Plugin API: Sandboxed; iframe and Electron have different capabilities. See 3.05-Web-App-vs-Desktop and the repo plugin guide.
• Further documentation: Sync Server README and auth docs in packages/super-sync-server/; Plugin API and examples in packages/plugin-api/, docs/plugin-development.md, and example plugins under packages/plugin-dev/.