REST API Reference

219 endpoints covering every feature. Ideal for automation and integration.

Basics

Ginkgo Backup exposes a REST API at 127.0.0.1:9275. All responses are JSON, timestamps are Unix microseconds (int64), and list endpoints support limit/offset pagination. Pro-only endpoints are marked with (Pro).

Base URL

http://127.0.0.1:9275

Authentication

All /api/v1/ endpoints (except /health and /settings/ca-cert) require a Bearer token. The token is auto-generated on first start and saved to ~/.ginkgo-backup/config.json. Localhost connections may be auto-authenticated depending on config.

Header

Authorization: Bearer <token>

Rate Limiting

600 requests/minute. Recommended polling intervals: backup progress 500ms, watch status 3s, checkpoints 30s, mount status 5s.

Response Format

Successful responses return a JSON object or array directly. Error responses:

Error

{
  "error": "description of the error",
  "code": "ERROR_CODE"
}

Pagination

List endpoints support limit and offset parameters. Responses include:

Example

{
  "items": [...],
  "total": 1000,
  "has_more": true
}

Endpoints

Health Check

Method	Path	Description
GET	`/api/v1/health`	Server health check (no auth)
GET	`/health`	Alias for /api/v1/health

Authentication

Method	Path	Description
POST	`/api/v1/auth/login`	Log in and obtain a session token
POST	`/api/v1/auth/logout`	Invalidate current session
GET	`/api/v1/auth/status`	Check auth status (returns needs_setup if no password set)
POST	`/api/v1/auth/setup-password`	Set initial password (first-time setup)
GET	`/api/v1/auth/login-audit`	List login audit logs
POST	`/api/v1/auth/revoke-sessions`	Revoke all other sessions
GET	`/api/v1/auth/totp/status`	Check TOTP 2FA status
POST	`/api/v1/auth/totp/setup`	Begin TOTP 2FA setup
POST	`/api/v1/auth/totp/confirm`	Confirm TOTP 2FA with verification code
POST	`/api/v1/auth/totp/disable`	Disable TOTP 2FA

System Status

Method	Path	Description
GET	`/api/v1/status`	System status overview
GET	`/api/v1/index/health`	Index DB health check
GET	`/api/v1/index/dedup`	Deduplication statistics
GET	`/api/v1/index/stats`	Index statistics
POST	`/api/v1/index/compact`	Compact the index DB
POST	`/api/v1/index/fix-first-seen`	Fix first-seen timestamps
GET	`/api/v1/watch/status`	File watch service status

Backup Sources

Method	Path	Description
GET	`/api/v1/sources`	List all backup sources
POST	`/api/v1/sources`	Create a backup source
GET	`/api/v1/sources/{id}`	Get source details
PUT	`/api/v1/sources/{id}`	Update source config
DELETE	`/api/v1/sources/{id}`	Delete a source

Backup Operations

Method	Path	Description
POST	`/api/v1/backup/run`	Trigger a backup
POST	`/api/v1/backup/preflight`	Pre-flight check before backup (estimates size, checks disk)
GET	`/api/v1/backup/progress`	Get current backup progress
GET	`/api/v1/backup/state`	Get backup state (idle/running/error)
POST	`/api/v1/backup/cancel`	Cancel a running backup
GET	`/api/v1/backup/checkpoints`	List backup checkpoints
GET	`/api/v1/backup/checkpoints/{id}`	Get checkpoint details
GET	`/api/v1/backup/recover-sessions`	List recoverable backup sessions

Snapshots

Method	Path	Description
GET	`/api/v1/snapshots`	List snapshots (query: source_id)
GET	`/api/v1/snapshots/{id}`	Get snapshot details
GET	`/api/v1/snapshots/changes`	List file changes in a snapshot
GET	`/api/v1/snapshots/space-estimate`	Estimate space for a snapshot

File Browsing & History

Method	Path	Description
GET	`/api/v1/files`	Browse files in a snapshot (FTS5 search supported)
GET	`/api/v1/history`	Get file version history
GET	`/api/v1/history/content`	Get file content at a version
GET	`/api/v1/history/diff`	Diff two versions of a file
GET	`/api/v1/history/download-zip`	Download multiple files as a zip
GET	`/api/v1/history/download-file`	Download a single file
POST	`/api/v1/history/restore`	Restore a single file from a snapshot

Restore Tasks

Method	Path	Description
POST	`/api/v1/restore`	Start a restore task (batch)
GET	`/api/v1/restore/tasks`	List restore tasks
GET	`/api/v1/restore/{id}`	Get restore task status

Repositories

Method	Path	Description
GET	`/api/v1/repositories`	List all repositories
POST	`/api/v1/repositories`	Create a repository
GET	`/api/v1/repositories/{id}`	Get repository details
PUT	`/api/v1/repositories/{id}`	Update repository
DELETE	`/api/v1/repositories/{id}`	Delete a repository
GET	`/api/v1/repo/compression-stats`	Get compression statistics
POST	`/api/v1/repo/scan`	Scan repository for existing data
POST	`/api/v1/repo/connect`	Connect to an existing repository
POST	`/api/v1/repo/sources-scan`	Scan sources in a repository
POST	`/api/v1/repo/import`	Import data into a repository
POST	`/api/v1/repo/delete-source-data`	Delete source data from a repository
GET	`/api/v1/repo/is-encrypted`	Check if repository is encrypted
POST	`/api/v1/repo/unlock`	Unlock a locked repository

GBF Low-Level Operations

Method	Path	Description
POST	`/api/v1/gb/init`	Initialize a GBF repository
POST	`/api/v1/gb/backup/run`	Trigger a GBF backup
POST	`/api/v1/gb/restore`	Restore from a GBF snapshot
POST	`/api/v1/gb/gc`	Run garbage collection on a GBF repo
GET	`/api/v1/gb/snapshots`	List GBF snapshots
POST	`/api/v1/gb/format`	Format a GBF repository
POST	`/api/v1/gb/retention`	Apply retention to a GBF repo

Cloud Storage

Method	Path	Description
GET	`/api/v1/cloud/backends`	List cloud backends
POST	`/api/v1/cloud/backends`	Create a cloud backend
GET	`/api/v1/cloud/backends/{id}`	Get backend details
PUT	`/api/v1/cloud/backends/{id}`	Update backend
DELETE	`/api/v1/cloud/backends/{id}`	Delete backend
POST	`/api/v1/cloud/backends/{id}/reauth`	Re-authorize a backend
POST	`/api/v1/cloud/backends/{id}/clear-cache`	Clear backend cache
POST	`/api/v1/cloud/test`	Test cloud connection
GET	`/api/v1/cloud/oauth2/start`	Start OAuth2 flow
GET	`/api/v1/cloud/oauth2/status`	Check OAuth2 status
GET	`/api/v1/cloud/oauth2/callback`	OAuth2 callback (no auth)
POST	`/api/v1/cloud/oauth2/submit-code`	Submit OAuth2 auth code
GET	`/api/v1/cloud/sources`	Discover cloud sources

Sync Jobs

Method	Path	Description
GET	`/api/v1/sync/jobs`	List sync jobs
GET	`/api/v1/pending-syncs`	List pending syncs

Retention & GC

Method	Path	Description
POST	`/api/v1/retention/apply`	Apply retention policy
POST	`/api/v1/retention/gc`	Run garbage collection
GET	`/api/v1/retention/gc/status`	Get GC status
GET	`/api/v1/retention/gc/directives`	Get GC directives
POST	`/api/v1/retention/verify`	Verify backup integrity
POST	`/api/v1/retention/cloud-gc`	Run cloud GC
GET	`/api/v1/retention/cloud-gc/status`	Get cloud GC status
POST	`/api/v1/retention/cloud-maintenance`	Run cloud maintenance
POST	`/api/v1/retention/delete-snapshots`	Delete specific snapshots
POST	`/api/v1/retention/remove-source-manifests`	Remove source manifests
POST	`/api/v1/retention/reset-safety`	Reset retention safety counter

Database Maintenance

Method	Path	Description
POST	`/api/v1/database/vacuum`	Vacuum the main SQLite DB
POST	`/api/v1/database/integrity-check`	Run SQLite integrity check
GET	`/api/v1/databases`	List external databases
GET	`/api/v1/databases/check-tool`	Check if DB backup tool is installed
POST	`/api/v1/databases/create`	Register an external database
GET	`/api/v1/databases/{id}`	Get database details
POST	`/api/v1/databases/{id}/update`	Update database config
POST	`/api/v1/databases/{id}/delete`	Delete database record
POST	`/api/v1/databases/{id}/test`	Test database connection
POST	`/api/v1/databases/{id}/backup`	Trigger a database backup
GET	`/api/v1/databases/{id}/tasks`	List database backup tasks
GET	`/api/v1/maintenance/scheduler/status`	Get maintenance scheduler status

Monitoring & Patrol

Method	Path	Description
GET	`/api/v1/oversight/health`	System health overview
GET	`/api/v1/oversight/alerts`	List active alerts
GET	`/api/v1/oversight/alerts/{id}`	Get alert details
GET	`/api/v1/oversight/cleanup-logs`	List cleanup/GC logs
POST	`/api/v1/oversight/delete-audit`	Delete audit log entries
GET	`/api/v1/oversight/delete-audit/stats`	Get delete audit stats
POST	`/api/v1/oversight/patrol`	Run patrol check
GET	`/api/v1/oversight/patrol/history`	Get patrol history
POST	`/api/v1/oversight/verify`	Run verification
POST	`/api/v1/oversight/repair`	Run repair operation

Cross-Repository Protection (Anti-Ransomware)

Method	Path	Description
POST	`/api/v1/cross-repo/backup`	Cross-repo config backup
GET	`/api/v1/cross-repo/alerts`	List cross-repo alerts
POST	`/api/v1/cross-repo/alerts/clear`	Clear cross-repo alerts
POST	`/api/v1/cross-repo/recover`	Cross-repo recovery
POST	`/api/v1/cross-repo/replicate`	Cross-repo replication
POST	`/api/v1/cross-repo/classify-path`	Classify a file path
POST	`/api/v1/cross-repo/vault-snapshot`	Create vault snapshot
POST	`/api/v1/cross-repo/config-snapshot`	Create config snapshot
POST	`/api/v1/cross-repo/config-restore`	Restore from config snapshot
POST	`/api/v1/cross-repo/verify-alerts`	Verify cross-repo alerts
POST	`/api/v1/cross-repo/ransomware-lock`	Enable ransomware lock

Settings

Method	Path	Description
GET	`/api/v1/settings`	Get app settings
PUT	`/api/v1/settings`	Update app settings
GET	`/api/v1/settings/api-info`	Get API info (version, port, TLS)
GET	`/api/v1/settings/cli-status`	Check CLI installation status
POST	`/api/v1/settings/install-cli`	Install CLI to user PATH
POST	`/api/v1/settings/uninstall-cli`	Uninstall CLI from PATH
GET	`/api/v1/settings/ca-cert`	Download CA certificate (public, no auth)
GET	`/api/v1/settings/ca-trust-status`	Check CA trust status
POST	`/api/v1/settings/trust-ca`	Install CA into trust store
GET	`/api/v1/settings/tls-sans`	List TLS SANs
POST	`/api/v1/settings/restart`	Restart the server
POST	`/api/v1/settings/regenerate-token`	Regenerate API token
PUT	`/api/v1/settings/webui-password`	Change WebUI password

Config Vault

Method	Path	Description
GET	`/api/v1/config-vault/targets`	List vault targets
POST	`/api/v1/config-vault/targets`	Create vault target
GET	`/api/v1/config-vault/targets/{id}`	Get vault target
PUT	`/api/v1/config-vault/targets/{id}`	Update vault target
DELETE	`/api/v1/config-vault/targets/{id}`	Delete vault target
POST	`/api/v1/config-vault/backup`	Run config vault backup
GET	`/api/v1/config-vault/health`	Get vault health

Encryption Keys

Method	Path	Description
POST	`/api/v1/keys/export`	Export encryption key
POST	`/api/v1/keys/import`	Import encryption key

Disaster Recovery

Method	Path	Description
POST	`/api/v1/recovery/start`	Start disaster recovery
POST	`/api/v1/recovery/cancel`	Cancel recovery
GET	`/api/v1/recovery/progress`	Get recovery progress
POST	`/api/v1/recovery-code/export`	Export recovery code
POST	`/api/v1/recovery-code/import`	Import recovery code

AI Integration

Method	Path	Description
POST	`/api/v1/integrations/ai/sync`	Sync AI tool rule files into a project
GET	`/api/v1/integrations/ai/status`	Get AI integration status
GET	`/api/v1/integrations/ai/diagnostics`	Get AI diagnostics context
GET	`/api/v1/integrations/ai/skill-templates`	Get AI skill template presets
POST	`/api/v1/ai/generate-note`	Generate AI snapshot note
POST	`/api/v1/ai/diagnose`	Run AI diagnosis (Pro)
POST	`/api/v1/ai/repair`	Run AI-guided repair (Pro)
POST	`/api/v1/ai/skill`	Invoke an AI skill (Pro)

Pins & Notes

Method	Path	Description
GET	`/api/v1/pins`	List pinned snapshots
POST	`/api/v1/pins/create`	Pin a snapshot (protect from GC)
POST	`/api/v1/pins/delete`	Unpin a snapshot
GET	`/api/v1/notes`	List snapshot notes
POST	`/api/v1/notes/cleanup-orphaned`	Clean up orphaned notes
POST	`/api/v1/notes/sync`	Sync notes to cloud

Sessions & Logs

Method	Path	Description
GET	`/api/v1/sessions`	List backup sessions
GET	`/api/v1/sessions/{id}`	Get session details
GET	`/api/v1/sessions/stats`	Get session statistics
GET	`/api/v1/logs`	List operation logs
GET	`/api/v1/logs/stats`	Get log statistics
GET	`/api/v1/logs/raw`	Get raw log entries

Staging

Method	Path	Description
POST	`/api/v1/staging/push`	Push files to staging area (general, preserves note_source)
POST	`/api/v1/staging/push-ai`	Push files marked AI-generated (forces note_source=ai)
GET	`/api/v1/staging/session`	Get current staging session

Mount & WebDAV

Method	Path	Description
POST	`/api/v1/mount/{source_id}`	Mount a snapshot as a filesystem
GET	`/api/v1/webdav/session`	Get WebDAV session info
*	`/webdav/`	WebDAV file access (all methods)

Filesystem Operations

Method	Path	Description
GET	`/api/v1/fs/browse`	Browse local filesystem
POST	`/api/v1/fs/mkdir`	Create directory

Notifications

Method	Path	Description
GET	`/api/v1/notify/config`	Get notification config
POST	`/api/v1/notify/test-email`	Send a test email
POST	`/api/v1/notify/test-webhook`	Send a test webhook

Bug Reports

Method	Path	Description
GET	`/api/v1/bug-reports`	List bug reports
GET	`/api/v1/bug-reports/{id}`	Get bug report details

License

Method	Path	Description
GET	`/api/v1/license/info`	Get license info
POST	`/api/v1/license/activate`	Activate a license key
POST	`/api/v1/license/deactivate`	Deactivate the license
POST	`/api/v1/license/handshake`	Verify license with server

Peer / Mesh Backup

Method	Path	Description
POST	`/peer/pair`	Pair a peer device (invitation code, no auth)
GET	`/peer/ping`	Peer ping (peer token auth)
GET	`/peer/repos`	List peer receive repos (peer token)
POST	`/peer/sync/{...}`	Begin/commit/fail a sync session (peer token)
POST	`/peer/blob/{...}`	Upload blob to peer repo (peer token)
GET	`/peer/list`	List blobs on peer (peer token)
GET	`/api/v1/peers`	List paired peers (WebUI)
POST	`/api/v1/peers/invite`	Generate a peer invitation
POST	`/api/v1/peers/pair`	Initiate pairing from local side
GET	`/api/v1/peers/{id}`	Get peer details
GET	`/api/v1/peer/discover`	Discover peers on LAN
GET	`/api/v1/peer-repos`	List local receive repos
GET	`/api/v1/peer-repos/{id}`	Get receive repo details

Plugins (Pro)

Method	Path	Description
GET	`/api/v1/plugins`	List plugins (Pro)
POST	`/api/v1/plugins/detect`	Detect installed plugins (Pro)
POST	`/api/v1/plugins/create-source`	Create a backup source from a plugin (Pro)
POST	`/api/v1/plugins/enable`	Enable a plugin (Pro)
POST	`/api/v1/plugins/disable`	Disable a plugin (Pro)
POST	`/api/v1/plugins/config`	Configure a plugin (Pro)
GET	`/api/v1/plugins/dependencies`	List plugin dependencies (Pro)
POST	`/api/v1/plugins/reload`	Reload plugins (Pro)
POST	`/api/v1/plugins/restore`	Restore from a plugin snapshot (Pro)
GET	`/api/v1/plugins/snapshots`	List plugin snapshots (Pro)

Notion Integration (Pro)

Method	Path	Description
GET/POST	`/api/v1/notion/config`	Get/set Notion config (Pro)
GET	`/api/v1/notion/accounts`	List Notion accounts
POST	`/api/v1/notion/sync`	Trigger Notion sync (Pro)
POST	`/api/v1/notion/test`	Test Notion connection (Pro)
POST	`/api/v1/notion/auto-setup`	Auto-setup Notion integration (Pro)
POST	`/api/v1/notion/delete`	Delete a Notion account (Pro)
POST	`/api/v1/notion/re-render`	Re-render Notion content (Pro)
GET	`/api/v1/notion/pages`	List Notion pages (Pro)
GET	`/api/v1/notion/page/{id}`	Get Notion page content (Pro)
GET	`/api/v1/notion/page-versions`	List page versions (Pro)
POST	`/api/v1/notion/export`	Export Notion pages (Pro)
GET	`/api/v1/notion/snapshots`	List Notion snapshots (Pro)
GET	`/api/v1/notion/attachment`	Get Notion attachment (Pro)
POST	`/api/v1/notion/mount`	Mount Notion workspace (Pro)
POST	`/api/v1/notion/unmount`	Unmount Notion workspace (Pro)
GET	`/api/v1/notion/mount-list`	List Notion mounts (Pro)

Team (Pro)

Method	Path	Description
POST	`/api/v1/team/invite`	Create team invitation (Pro)
POST	`/api/v1/team/join`	Join a team (Pro)
GET	`/api/v1/team/invite-info`	Get invitation info (Pro)

Example: Create a source and trigger a backup

curl

curl -X POST http://127.0.0.1:9275/api/v1/sources \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/home/user/documents",
    "name": "My Documents",
    "schedule": "daily",
    "schedule_config": "{\"hour\":2,\"minute\":30}",
    "retention": "smart",
    "excludes": ["*.tmp", "node_modules"],
    "compression_type": "zstd",
    "repo_paths": ["/backup/repo1"]
  }'

# Trigger a backup
curl -X POST http://127.0.0.1:9275/api/v1/backup/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source_id": 1}'

# Poll progress
curl http://127.0.0.1:9275/api/v1/backup/progress \
  -H "Authorization: Bearer $TOKEN"

REST API Reference

Basics

Authentication

Rate Limiting

Response Format

Pagination

Endpoints

Health Check

Authentication

System Status

Backup Sources

Backup Operations

Snapshots

File Browsing & History

Restore Tasks

Repositories

GBF Low-Level Operations

Cloud Storage

Sync Jobs

Retention & GC

Database Maintenance

Monitoring & Patrol

Cross-Repository Protection (Anti-Ransomware)

Settings

Config Vault

Encryption Keys

Disaster Recovery

AI Integration

Pins & Notes

Sessions & Logs

Staging

Mount & WebDAV

Filesystem Operations

Notifications

Bug Reports

License

Peer / Mesh Backup

Plugins (Pro)

Notion Integration (Pro)

Team (Pro)

Example: Create a source and trigger a backup

See Also