List Backups

GET /v1/applications/{uuid}/backups

List every backup for an application, along with what your plan lets you do. A backup captures the app's managed database (a gzipped SQL dump), its content volume (a gzipped tar), or both. Database backups apply to any managed app with a bound managed database; content backups apply to apps with a content volume (e.g. Managed WordPress).

Response (200 OK)

locked bool
true when your plan grants none of the backup entitlements — nothing on this app can be backed up or restored.
capabilities object
Which operations are available for this app on your plan: db_backup, db_restore, content_backup, content_restore, schedule (all bool). Each is true only when the app has that resource and the plan entitles the op.
retention_max int
The plan cap on how many backups a schedule retains (backup_retention_max).
items array
The backups, newest first (see the object fields below).
schedule object | null
The current automatic schedule, or null if none (see Get Backup Schedule).

Backup object

uuid string
The backup identifier.
kind string
database, content, or full.
trigger_source string
manual or scheduled.
status string
pending, running, completed, failed, or deleting.
restore_status string
none, restoring, restored, or failed.
db_size_bytes / content_size_bytes int
Size of the captured SQL dump and content tar.
error / restore_error string | null
Failure detail for the backup / restore, when failed.
created_at / completed_at / restored_at string
Timestamps for creation, completion, and last restore.
Request
curl "https://api.ngris.com/v1/applications/a1b2c3d4-…/backups" \ -H "X-API-KEY: <your_api_key>"
Response — 200 OK
{ "locked": false, "capabilities": { "db_backup": true, "db_restore": true, "content_backup": true, "content_restore": true, "schedule": true }, "retention_max": 14, "items": [ { "uuid": "bk_9f2a…", "kind": "full", "trigger_source": "manual", "status": "completed", "restore_status": "none", "db_size_bytes": 1048576, "content_size_bytes": 8388608, "error": null, "restore_error": null, "created_at": "2026-08-12T03:00:00Z", "completed_at": "2026-08-12T03:00:42Z", "restored_at": null } ], "schedule": { "enabled": true, "kind": "full", "frequency": "daily", "hour_utc": 3, "retain_count": 7, "last_run_at": "2026-08-12T03:00:00Z", "next_run_at": "2026-08-13T03:00:00Z" } }

Create a Backup

POST /v1/applications/{uuid}/backups

Take a backup on demand. Ngris queues the job; the backup is created with status: "pending" and moves to completed when the dump and upload finish. Only one backup runs at a time per app.

Request body (application/json)

kind string
database, content, or full (the default). database dumps the managed database; content archives the content volume; full does both, whichever the app has.

Response (201 Created)

Returns the newly created backup object (same shape as in the list).

Errors

400
Invalid kind, no ready managed database for a database backup, or no content volume for a content backup.
403
Database backup is not available on your plan. / Content backup is not available on your plan.
409
A backup is already in progress.
Request
curl -X POST \ "https://api.ngris.com/v1/applications/a1b2c3d4-…/backups" \ -H "X-API-KEY: <your_api_key>" \ -H "Content-Type: application/json" \ -d '{ "kind": "full" }'
Response — 201 Created
{ "uuid": "bk_a71c…", "kind": "full", "trigger_source": "manual", "status": "pending", "restore_status": "none", "created_at": "2026-08-12T12:00:00Z" }

Restore a Backup

POST /v1/applications/{uuid}/backups/{backup_uuid}/restore
⚠ Destructive. Restore overwrites the app's current database and/or content volume with the backup's contents. There is no undo — anything written since the backup was taken is replaced. In the dashboard this is behind an explicit confirmation.

Restore a completed backup into the running app. The call is accepted asynchronously; poll GET /backups and watch the backup's restore_status (restoring → restored, or failed). The restore is gated by the entitlement that matches the backup's kind — database restore for a database backup, content restore for a content backup.

Response (202 Accepted)

status string
restoring.

Errors

403
Database restore is not available on your plan. / Content restore is not available on your plan. (matched to the backup's kind).
404
Application or backup not found.
409
Only a completed backup can be restored.
Request
curl -X POST \ "https://api.ngris.com/v1/applications/a1b2c3d4-…/backups/bk_9f2a…/restore" \ -H "X-API-KEY: <your_api_key>"
Response — 202 Accepted
{ "status": "restoring" }

Download a Backup Artifact

GET /v1/applications/{uuid}/backups/{backup_uuid}/download

Stream a completed backup's raw artifact for an off-platform copy. The database artifact is a gzipped SQL dump; the content artifact is a gzipped tar of the content volume. The response is Content-Type: application/gzip, served as an attachment.

Query parameters

artifact string
database (the default) or content.

Errors

404
Application, backup, or the requested artifact not found.
409
The backup is not completed yet.
503
The stored artifact is temporarily unavailable.
Request — database dump
curl -L -o backup-db.sql.gz \ "https://api.ngris.com/v1/applications/a1b2c3d4-…/backups/bk_9f2a…/download?artifact=database" \ -H "X-API-KEY: <your_api_key>"
Request — content volume
curl -L -o backup-content.tar.gz \ "https://api.ngris.com/v1/applications/a1b2c3d4-…/backups/bk_9f2a…/download?artifact=content" \ -H "X-API-KEY: <your_api_key>"

Delete a Backup

DELETE /v1/applications/{uuid}/backups/{backup_uuid}

Remove a backup — both its stored artifacts (the SQL dump and content tar) and its record. This is permanent.

Response (204 No Content)

An empty body on success.

Errors

404
Application or backup not found.
Request
curl -X DELETE \ "https://api.ngris.com/v1/applications/a1b2c3d4-…/backups/bk_9f2a…" \ -H "X-API-KEY: <your_api_key>"
Response — 204 No Content
(empty)

Get Backup Schedule

GET /v1/applications/{uuid}/backup-schedule

Read the app's automatic backup schedule and the plan's retention cap. A schedule runs one backup of the chosen kind daily or weekly at a fixed UTC hour, keeping the most recent retain_count backups.

Response (200 OK)

schedule object | null
null when no schedule is set; otherwise the schedule object.
schedule.enabled bool
Whether the schedule is active.
schedule.kind string
database, content, or full.
schedule.frequency string
daily or weekly.
schedule.hour_utc int
Hour of day in UTC, 0–23.
schedule.retain_count int
How many scheduled backups to keep (clamped to retention_max).
schedule.last_run_at / next_run_at string
Last and next scheduled run.
retention_max int
The plan cap on retained backups (backup_retention_max).
Request
curl "https://api.ngris.com/v1/applications/a1b2c3d4-…/backup-schedule" \ -H "X-API-KEY: <your_api_key>"
Response — 200 OK
{ "schedule": { "enabled": true, "kind": "full", "frequency": "daily", "hour_utc": 3, "retain_count": 7, "last_run_at": "2026-08-12T03:00:00Z", "next_run_at": "2026-08-13T03:00:00Z" }, "retention_max": 14 }

Update Backup Schedule

PUT /v1/applications/{uuid}/backup-schedule

Create or update the automatic backup schedule. retain_count is clamped to the plan's backup_retention_max. Enabling a schedule requires the application_backup_schedule entitlement; a downgraded account may still disable one. Automatic schedules are auto-disabled if the account later loses the entitlement.

Request body (application/json)

enabled bool
Turn the schedule on or off.
kind string
database, content, or full.
frequency string
daily or weekly.
hour_utc int
Hour of day in UTC to run, 0–23.
retain_count int
How many scheduled backups to keep. Clamped to the plan's retention cap.

Response (200 OK)

Returns the saved schedule under schedule.

Errors

403
Scheduled backups are not available on your plan. (only when enabled: true).
Request
curl -X PUT \ "https://api.ngris.com/v1/applications/a1b2c3d4-…/backup-schedule" \ -H "X-API-KEY: <your_api_key>" \ -H "Content-Type: application/json" \ -d '{ "enabled": true, "kind": "full", "frequency": "daily", "hour_utc": 3, "retain_count": 7 }'
Response — 200 OK
{ "schedule": { "enabled": true, "kind": "full", "frequency": "daily", "hour_utc": 3, "retain_count": 7, "next_run_at": "2026-08-13T03:00:00Z" } }
Homepage Docs Dashboard Docs API Docs nvelox Dashboard
Iris