API Reference - Backups

The Backups API lets you manage NetBox Cloud backups programmatically. It covers three operations:

• Request Backups -- trigger on-demand backups and list existing backups
• Retrieve Backups -- request download access to a backup file
• Restore Backups -- restore a NetBox instance from a retrieved backup

Each operation has its own Read and Write permission. Assign permissions when creating your API key.

Pagination

List responses follow this structure:

{
  "data": [],
  "metadata": {
    "pagination": {
      "current_page": 1,
      "page_size": 100,
      "total_items": 42,
      "total_pages": 1,
      "first_page": true,
      "last_page": false
    }
  }
}

---

Request Backups

Use Request Backups to list existing backups and trigger new ones.

Required permission: Read (GET) or Write (POST)

List backups

GET /v2/organization/{org_id}/backups/

Query parameters:

Parameter	Type	Description
initial_date	string (YYYY-MM-DD)	Optional. Filter by start date. UTC
end_date	string (YYYY-MM-DD)	Optional. Filter by end date. UTC
page	string	Optional. Page number (default: 1)
page_size	string	Optional. Results per page (default: 100)

Example response item:

{
  "id": "67a6a02d-0b23-4c7b-b7fa-08d4aa7643ab",
  "obj_id": "nb-a12ff000777",
  "obj_type": "netbox",
  "obj_version": "4.2.9",
  "trigger_id": "",
  "trigger_type": "scheduled",
  "checksum": "a21ae13...",
  "size_bytes": 220673,
  "duration": 47, //seconds
  "created": "2026-03-23T01:17:10.802995Z"
}

List backup requests

GET /v2/organization/{org_id}/backup-requests/

Query parameters:

Parameter	Type	Description
page	string	Optional. Page number (default: 1)
page_size	string	Optional. Results per page (default: 100)

Example response item:

{
  "id": "254fdc9b-ca40-4e13-b500-c8884ecb69be",
  "obj_id": "nb-a12ff000777",
  "obj_type": "netbox",
  "created": "2026-03-21T08:38:17.159662Z",
  "started": "2026-03-21T08:38:18.543679Z",
  "completed": "2026-03-21T08:39:06.753242Z"
}

Request a backup

POST /v2/organization/{org_id}/backup-requests/

Request body:

{
  "obj_id": "nb-a12ff000777",
  "obj_type": "netbox"
}

Field	Description
obj_id	Required. The ID of the NetBox instance to back up (for example, nb-aabbccddee01)
obj_type	Required. Always "netbox"

Example response:

{
  "id": "24b8878d-36c8-4d56-97cd-cd21fa575ebb"
}

The response id is the backup request ID. Use List backup requests to check its status.

---

Retrieve Backups

Use Retrieve Backups to request download access to a backup file. A retrieval generates a time-limited download URL.

Required permission: Read (GET) or Write (POST)

List retrievals

GET /v2/organization/{org_id}/backup-retrieved/

Query parameters:

Parameter	Type	Description
page	string	Optional. Page number (default: 1)
page_size	string	Optional. Results per page (default: 100)

Example response item:

{
  "id": "97c6c02d-0b23-4c7b-b7fa-08d4aa7643cd",
  "backup_id": "6eaaef10-471b-4226-bc30-852ead73ee83",
  "backup_version": "4.2.9",
  "presigned_url": "https://backup_retrieval.netboxlabs.com/...",
  "created": "2026-03-23T19:39:23.935566Z",
  "created_by": "user@example.com",
  "started": "2026-03-23T19:39:25.226295Z",
  "completed": "2026-03-23T19:39:26.307355Z",
  "expires": "2026-03-23T22:39:26.288072Z"
}

The presigned_url field contains a time-limited URL for downloading the backup file. It is valid until the datetime in the expires field.

Request a retrieval

POST /v2/organization/{org_id}/backup-retrieved/

Request body:

{
  "backup_id": "80acb50b-c08e-4233-bc32-bf8f5ce61031"
}

The backup_id field is required. Use the id from a backup in List backups.

Example response:

{
  "id": "005bf3ba-aa63-43de-a45b-f8db03e5fdfe"
}

The response id is the retrieval ID. Use List retrievals to check its status and get the download URL once processing completes.

---

Restore Backups

Use Restore Backups to restore a NetBox instance from a previously retrieved backup.

Required permission: Read (GET) or Write (POST)

List restore jobs

GET /v2/organization/{org_id}/backup-restore/

Query parameters:

Parameter	Type	Description
target_nb_id	string	Optional. Filter by target NetBox instance ID

Example response item:

{
  "id": "6910836b-d767-44f1-8e5d-9fab2109f751",
  "retrieval_id": "d622056f-098f-457d-a560-80ebb35a710b",
  "target_nb_id": "nb-a12ff000777",
  "target_version_available": false,
  "created": "2026-03-24T06:29:26.179537Z",
  "created_by": "user@example.com",
  "started": "2026-03-24T06:29:29.321058Z",
  "completed": "2026-03-24T06:29:48.624347Z",
  "failed": null,
  "nb_redeployed": "2026-03-24T06:29:51.834606Z"
}

Request a restore

POST /v2/organization/{org_id}/backup-restore/

Request body:

{
  "retrieval_id": "84d4a841-1163-4967-b0b0-9b9da03a570e",
  "target_nb_id": "nb-b23ff000888"
}

Both fields are required. Use a retrieval_id from List retrievals once the retrieval has completed.

Example response:

{
  "id": "d62d6a2d-83bc-49ef-8462-8aca35382a8c"
}

The response id is the restore job ID. Use List restore jobs to check its status.

Additional response codes:

Status	Meaning
422 Unprocessable Entity	The request is valid but cannot be processed, for example if the target version is not available