your servers, your code
Trigger backups, start restores, update schedules, and monitor your game servers programmatically. Build automation that reacts to your servers in real time.
curl -X POST \
-H "Authorization: Bearer narwhal_live_..." \
https://pinknarwhal.com/api/v1/servers/1/backups{
"data": {
"server_id": 1,
"server_name": "Survival SMP",
"message": "Backup queued"
}
}what you can do with it
the same operations available in the dashboard, accessible from your own code.
Manage Servers
List all your connected servers, update display names, change backup schedules, and pause or resume backups programmatically.
Trigger Backups
Start a manual backup for any server on demand. Perfect for pre-update snapshots or CI/CD pipelines that need a safety net before deploying.
Start Restores
Kick off a full or selective restore via the API. Specify exact file paths for surgical recovery, or restore everything at once.
Monitor Usage
Check your storage consumption, server count, and plan limits. Build dashboards or alerts that track your backup health.
Secure by Default
Bearer token authentication with SHA-256 hashed keys. Rate limited to 60 requests per minute per key. Scoped to your organization and revocable from the dashboard at any time.
Simple JSON Responses
Every endpoint returns clean, consistent JSON wrapped in a data envelope. No XML, no SOAP, no surprises. Standard HTTP status codes throughout.
9 endpoints. one API key.
REST. JSON. standard HTTP. nothing weird.
/api/v1/serversList all servers/api/v1/servers/:idGet server details/api/v1/servers/:idUpdate a server/api/v1/servers/:id/backupsList backups for a server/api/v1/servers/:id/backupsTrigger a manual backup/api/v1/backups/:idGet backup details and manifest/api/v1/backups/:id/restoreStart a restore/api/v1/restores/:idCheck restore progress/api/v1/usageGet storage and usage statsthings people actually build with this
not just an API for the sake of it. these are the workflows server owners actually build.
Auto-restore on crash detection
Monitor your server with a watchdog script. If the process crashes or health checks fail, trigger an API restore to roll back to the last known good backup automatically. Before players even notice.
Pre-update safety snapshots
Integrate with your deployment pipeline. Before pushing a Rust wipe, a Minecraft plugin update, or a config change, trigger a backup via the API so you always have a clean rollback point.
Custom scheduling and orchestration
Build your own backup logic on top of Pink Narwhal. Trigger backups based on player count, time of day, or events in your game. Pause backups during maintenance windows and resume when you are done.
Multi-server fleet management
Running a network? Script bulk operations across all your servers. List every server, check which ones have stale backups, and trigger catch-up backups in a single loop.
Storage monitoring and alerts
Poll the usage endpoint and feed it into your existing monitoring stack. Grafana, Datadog, or a Discord webhook. Get alerted before you hit storage limits, not after.
Selective file recovery
Fetch a backup's manifest to see every file inside, then restore only the ones you need. Build file pickers into your own panel, Discord bot, or admin tool. No dashboard access required.
frequently asked questions
You can list servers, trigger manual backups, start full or selective restores, update backup schedules, pause or unpause servers, and check your storage usage. Everything you can do in the dashboard, you can do programmatically.
API access is available on the Pro plan ($12.99/mo) and Network plan ($25.99/mo). Starter plan users can view the documentation but need to upgrade to generate API keys.
Generate an API key from your dashboard under the API section. Include it as a Bearer token in the Authorization header of every request. Keys are scoped to your organization and can be revoked instantly.
Yes. Send a POST request to /api/v1/backups/:id/restore with the restore type (full or selective). For selective restores, include an array of file paths to recover. Poll the restore status endpoint to track progress in real time.
Yes. Each API key is limited to 60 requests per minute using a sliding window. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so your code can track usage. If you exceed the limit you will receive a 429 status with a Retry-After header.
Yes. Every action performed via the API is logged in your organization's audit log with the API key name clearly identified, so you always know what happened and which key triggered it.
pricing. it's not complicated.
every plan starts with a free trial. no contracts. cancel whenever.
API key, first request, two minutes.
available on Pro and Network plans. free trial included.