Sync API

The Sync API enables the local desktop client (Tauri) to synchronize data and files with the server. All endpoints use Bearer token authentication.

Base path: /api/sync/

Authentication

Login

POST /api/sync/auth.php?action=login
Content-Type: application/json

{
  "username": "user",
  "password": "password",
  "device_name": "MacBook Pro",
  "device_id": "a1b2c3d4e5f6g7h8"
}

device_id must be at least 8 characters.

Response (Success):

{
  "ok": true,
  "token": "64-character-hex-string",
  "user": {
    "id": 1,
    "username": "user",
    "display_name": "User Name"
  }
}

Response (2FA Required):

{
  "ok": true,
  "requires_2fa": true,
  "pending_token": "temporary-token"
}

Complete 2FA

POST /api/sync/auth.php?action=login_2fa
Content-Type: application/json

{
  "pending_token": "temporary-token",
  "code": "123456"
}

Pending token expires after 5 minutes. Accepts TOTP code or backup code.

Validate Token

POST /api/sync/auth.php?action=validate
Authorization: Bearer <token>

List Devices

GET /api/sync/auth.php?action=devices
Authorization: Bearer <token>

Revoke Device

POST /api/sync/auth.php?action=revoke
Authorization: Bearer <token>
Content-Type: application/json

{
  "token_id": 5
}

Logout

POST /api/sync/auth.php?action=logout
Authorization: Bearer <token>

Data Sync

Initial Sync

Full data dump for first sync.

GET /api/sync/data.php?action=initial_sync
Authorization: Bearer <token>

Rate limit: 5 requests/minute

Response:

{
  "ok": true,
  "data": {
    "niuton_notes": [...],
    "niuton_finance": [...],
    "niuton_docs": [...],
    "niuton_places": [...]
  },
  "cursor": 12345,
  "schema_version": 7
}

Delta Sync

Incremental changes since last sync.

GET /api/sync/data.php?action=delta&cursor=12345&limit=1000
Authorization: Bearer <token>

Parameters:

Name	Type	Default	Max	Description
cursor	integer	required	—	Last known sync cursor
limit	integer	1000	5000	Max changes to return

Rate limit: 30 requests/minute

Response:

{
  "ok": true,
  "changes": [
    {
      "table": "niuton_notes",
      "operation": "UPDATE",
      "data": { "id": 5, "title": "Updated Note", ... },
      "cursor": 12346
    }
  ],
  "cursor": 12350,
  "has_more": false,
  "count": 5
}

Push Changes

Push client-side changes to server.

POST /api/sync/data.php?action=push
Authorization: Bearer <token>
Content-Type: application/json

{
  "operations": [
    {
      "table": "niuton_notes",
      "operation": "INSERT",
      "data": {
        "title": "New Note",
        "content": "Content here",
        "category": "General"
      }
    },
    {
      "table": "niuton_notes",
      "operation": "UPDATE",
      "data": {
        "id": 5,
        "title": "Updated Title"
      }
    }
  ]
}

Rate limit: 30 requests/minute
Max operations: 100 per push

File Sync

Manifest

Get complete file listing with checksums.

GET /api/sync/files.php?action=manifest
Authorization: Bearer <token>

Rate limit: 10 requests/minute

Response:

{
  "ok": true,
  "files": [
    {
      "path": "/Documents/notes.md",
      "size": 1234,
      "sha256": "abc123...",
      "mtime": 1708444800
    }
  ]
}

Download File

GET /api/sync/files.php?action=download&path=/Documents/notes.md
Authorization: Bearer <token>

Rate limit: 120 requests/minute

Returns binary file with headers:

• X-File-SHA256 — File checksum
• X-File-MTime — Modification time

Upload File

POST /api/sync/files.php?action=upload&path=/Documents/new-file.md
Authorization: Bearer <token>
Content-Type: multipart/form-data (or raw body)

file: <binary>

Rate limit: 60 requests/minute
Optional mtime parameter to preserve client modification time.

Delete

POST /api/sync/files.php?action=delete
Authorization: Bearer <token>
Content-Type: application/json

{
  "path": "/Documents/old-file.md"
}

Idempotent — returns already_deleted if file doesn't exist.

Create Directory

POST /api/sync/files.php?action=mkdir
Authorization: Bearer <token>
Content-Type: application/json

{
  "path": "/Documents/NewFolder"
}

Move

POST /api/sync/files.php?action=move
Authorization: Bearer <token>
Content-Type: application/json

{
  "from": "/Documents/old.md",
  "to": "/Documents/new.md"
}

Returns 409 if target already exists.

Server Status

Health Check (No Auth)

GET /api/sync/status.php?action=ping

{
  "status": "ok",
  "timestamp": "2026-02-21T12:00:00Z"
}

Server Info

GET /api/sync/status.php?action=info
Authorization: Bearer <token>

{
  "ok": true,
  "app_version": "3.7",
  "sync_schema_version": 7,
  "maintenance_mode": false,
  "current_cursor": 12350,
  "synced_tables": ["niuton_notes", "niuton_finance", ...],
  "feature_flags": {
    "delta_sync": true,
    "file_sync": true,
    "team_chat": true,
    "chess": true,
    "2fa": true,
    "conflict_copy": true
  }
}

Token Security

• Tokens are 64-character hex strings
• Stored as SHA-256 hashes in niuton_api_tokens table
• Each device gets its own token
• Tokens can be individually revoked