For the complete documentation index, see llms.txt. This page is also available as Markdown.

Operations API

Learn how to manage Cloudback backup definitions programmatically using the Operations API for automated backup configuration across supported platforms.

Overview

The Cloudback Operations API allows users to manage backup definitions programmatically. It provides a RESTful interface to update backup definitions for repositories across all supported platforms.

Features

  • Automated backup definition configuration for repositories
  • Programmatic management of backup configurations
  • Multi-platform support

Prerequisites

Before you begin, ensure that you have the following:

  • Cloudback Account: An active account with appropriate permissions to create and manage backup resources.
  • API Key: Your API key for Cloudback's API. You can create one at the API Keys page in the Cloudback dashboard.
  • Network Access: Ensure that your environment can reach Cloudback's endpoints: https://app.cloudback.it/ops/

API Reference

Read Backup Status and History

Endpoint: POST /ops/definition/backups

Read the current enabled flag and state plus up to three latest backup records for one repository or workspace. Use an existing account Operations API key.

POST https://app.cloudback.it/ops/definition/backups
Content-Type: application/json
Accept: application/json
X-API-Key: your-api-key

{
  "platform": "GitHub",
  "account": "my-organization",
  "subjectName": "demo-repository",
  "subjectType": "Repository"
}
{
  "definitionId": 42,
  "platform": "GitHub",
  "account": "my-organization",
  "backupSubjectName": "demo-repository",
  "backupSubjectType": "Repository",
  "isEnabled": true,
  "state": "CanBackupAndRestore",
  "items": [
    {
      "backupId": 9003,
      "status": "InProgress",
      "triggerType": "Manual",
      "queueTimeUtc": "2026-11-06T10:00:00Z",
      "startTimeUtc": "2026-11-06T10:00:02Z",
      "endTimeUtc": null
    }
  ]
}

Use the same account and subject fields as the examples below for your platform. Reading status does not change your backup settings or start a backup.

To use the response in your monitoring:

  • Check isEnabled and state: automated backups need isEnabled: true and state: CanBackupAndRestore. You can also check disabled or restore-only backups.
  • Look at items for the latest backups, newest first. Succeeded, Failed, Queued and InProgress help you spot a recent success, failure or pending run. An empty list means no backup history is available.
  • Use triggerType to distinguish Scheduled and Manual backups. Undefined means the trigger is unknown.
  • All times are in UTC. queueTimeUtc records when the backup was queued; startTimeUtc can change when a backup starts or is retried. For a queued backup, it does not mean work has started. endTimeUtc can be null if no end time is available.

Only the latest three backups are returned. If none succeeded, an older successful backup may still exist; keep earlier results if you need to track success over time. Retries can update an existing backup's status and times. A Deleted record cannot be downloaded, and older history may no longer be available.

If you receive a 401 response, check that your API key belongs to the requested account. For other errors, see Error Responses.

Get Backup Definition

Retrieve the current backup configuration for a repository.

Endpoint: POST /ops/definition/get

GitHub Example

POST https://app.cloudback.it/ops/definition/get
Content-Type: application/json
X-API-Key: your-api-key

{
  "platform": "GitHub",
  "account": "cloudback",
  "subjectName": "demo-repository",
  "subjectType": "Repository"
}

Azure DevOps Repository Example

POST https://app.cloudback.it/ops/definition/get
Content-Type: application/json
X-API-Key: your-api-key

{
  "platform": "AzureDevOps",
  "account": "my-organization",
  "subjectName": "my-project/demo-repository",
  "subjectType": "Repository"
}

Azure DevOps Project Example

POST https://app.cloudback.it/ops/definition/get
Content-Type: application/json
X-API-Key: your-api-key

{
  "platform": "AzureDevOps",
  "account": "my-organization",
  "subjectName": "my-project",
  "subjectType": "Project"
}

GitLab Example

POST https://app.cloudback.it/ops/definition/get
Content-Type: application/json
X-API-Key: your-api-key

{
  "platform": "GitLab",
  "account": "my-group",
  "subjectName": "my-project",
  "subjectType": "Project"
}

Linear Example

POST https://app.cloudback.it/ops/definition/get
Content-Type: application/json
X-API-Key: your-api-key

{
  "platform": "Linear",
  "account": "my-workspace-key",
  "subjectName": "my-workspace",
  "subjectType": "Workspace"
}

Response

HTTP/1.1 200 OK
{
  "platform": "GitHub",
  "account": "cloudback",
  "backupSubjectName": "demo-repository",
  "backupSubjectType": "Repository",
  "settings": {
    "enabled": true,
    "schedule": "Daily at 9 pm",
    "storage": "Cloudback EU",
    "retention": "Last 30 days"
  }
}

Update Backup Definition

Update the backup configuration for a repository.

Endpoint: POST /ops/definition/update

GitHub Example

POST https://app.cloudback.it/ops/definition/update
Content-Type: application/json
X-API-Key: your-api-key

{
  "platform": "GitHub",
  "account": "cloudback",
  "subjectName": "demo-repository",
  "subjectType": "Repository",
  "settings": {
    "enabled": true,
    "schedule": "Daily at 9 pm",
    "storage": "Cloudback EU",
    "retention": "Last 30 days"
  }
}

Azure DevOps Example

POST https://app.cloudback.it/ops/definition/update
Content-Type: application/json
X-API-Key: your-api-key

{
  "platform": "AzureDevOps",
  "account": "my-organization",
  "subjectName": "my-project/demo-repository",
  "subjectType": "Repository",
  "settings": {
    "enabled": true,
    "schedule": "Daily at 9 pm",
    "storage": "Cloudback EU",
    "retention": "Last 30 days"
  }
}

GitLab Example

POST https://app.cloudback.it/ops/definition/update
Content-Type: application/json
X-API-Key: your-api-key

{
  "platform": "GitLab",
  "account": "my-group",
  "subjectName": "my-project",
  "subjectType": "Project",
  "settings": {
    "enabled": true,
    "schedule": "Daily at 9 pm",
    "storage": "Cloudback EU",
    "retention": "Last 30 days"
  }
}

Linear Example

POST https://app.cloudback.it/ops/definition/update
Content-Type: application/json
X-API-Key: your-api-key

{
  "platform": "Linear",
  "account": "my-workspace-key",
  "subjectName": "my-workspace",
  "subjectType": "Workspace",
  "settings": {
    "enabled": true,
    "schedule": "Daily at 9 pm",
    "storage": "Cloudback EU",
    "retention": "Last 30 days"
  }
}

Response

HTTP/1.1 200 OK
{
  "platform": "GitHub",
  "account": "cloudback",
  "backupSubjectName": "demo-repository",
  "backupSubjectType": "Repository",
  "settings": {
    "enabled": true,
    "schedule": "Daily at 9 pm",
    "storage": "Cloudback EU",
    "retention": "Last 30 days"
  }
}

Request Data Model

FieldTypeRequiredDescription
platformstringYesThe platform. Values: GitHub, AzureDevOps, GitLab, Linear
accountstringYesThe account or organization name
subjectNamestringYesThe name of the backup subject (see below)
subjectTypestringYesThe type of backup subject: Repository, Project, or Workspace (Linear only)
settingsobjectYes*The backup configuration settings (*required for update)

Subject Name Format

The subjectName format varies by platform:

PlatformSubject TypeFormatExample
GitHubRepositoryrepository-namedemo-repository
Azure DevOpsRepositoryproject-name/repository-namemy-project/demo-repo
Azure DevOpsProjectproject-namemy-project
GitLabProjectproject-namemy-project
LinearWorkspaceworkspace-namemy-workspace

Settings Object

FieldTypeRequiredDescription
enabledbooleanNoWhether automated backup is enabled
schedulestringNoBackup schedule name (see schedules)
storagestringNoStorage location name (see storages)
retentionstringNoRetention policy: Last 30 days, Last 90 days, Last 180 days, Last 360 days

Response Data Model

FieldTypeDescription
platformstringThe platform (GitHub, AzureDevOps, GitLab, or Linear)
accountstringThe account or organization name
backupSubjectNamestringThe name of the backup subject
backupSubjectTypestringThe type: Repository, Project, or Workspace (Linear only)
settingsobjectThe current backup configuration

Error Responses

Status CodeDescription
400 Bad RequestInvalid request format or parameters
401 UnauthorizedAPI key is missing or invalid
402 Payment RequiredPlan limit exceeded
404 Not FoundReserved for repository not found cases; in practice, account not found and definition not found errors are currently returned as 400 Bad Request
422 Unprocessable EntityValidation error (e.g., schedule not found)

Error Response Body

For most errors (400, 404, 422), the response body contains the error message as a plain JSON string. The 401 Unauthorized response has an empty body.

"Account not found"

For 402 Payment Required, the response uses the RFC 7807 Problem Details format:

{
  "type": "https://httpstatuses.org/402",
  "title": "Plan Limit Exceeded",
  "status": 402,
  "detail": "The plan limit has been exceeded for this account"
}

Backwards Compatibility

For backwards compatibility, the repository field is still accepted in requests as an alias for subjectName. If both are provided, subjectName takes precedence. If subjectType is not provided, it defaults to Repository.

# Legacy format (still supported)
{
  "platform": "GitHub",
  "account": "cloudback",
  "repository": "demo-repository"
}

# Equivalent modern format
{
  "platform": "GitHub",
  "account": "cloudback",
  "subjectName": "demo-repository",
  "subjectType": "Repository"
}

Platform-Specific Notes

GitHub

  • account: GitHub username or organization name
  • subjectName: Repository name
  • subjectType: Always Repository

Azure DevOps

  • account: Azure DevOps organization name
  • subjectName: For repositories use project/repository format; for projects use just the project name
  • subjectType: Use Repository for repository backups, Project for project-level backups
  • Ensure the Azure DevOps organization has Cloudback authorized

GitLab

  • account: GitLab group name or personal namespace
  • subjectName: Project name
  • subjectType: Always Project

Linear

  • account: Linear workspace key (the short identifier for the workspace)
  • subjectName: Linear workspace name
  • subjectType: Always Workspace
  • Each Linear workspace is backed up as a single unit; the Workspace subject type is unique to Linear

References

Last updated

Questions or feedback? Email support