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

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

Field	Type	Required	Description
`platform`	string	Yes	The platform. Values: `GitHub`, `AzureDevOps`, `GitLab`, `Linear`
`account`	string	Yes	The account or organization name
`subjectName`	string	Yes	The name of the backup subject (see below)
`subjectType`	string	Yes	The type of backup subject: `Repository`, `Project`, or `Workspace` (Linear only)
`settings`	object	Yes*	The backup configuration settings (*required for update)

Subject Name Format

The subjectName format varies by platform:

Platform	Subject Type	Format	Example
GitHub	Repository	`repository-name`	`demo-repository`
Azure DevOps	Repository	`project-name/repository-name`	`my-project/demo-repo`
Azure DevOps	Project	`project-name`	`my-project`
GitLab	Project	`project-name`	`my-project`
Linear	Workspace	`workspace-name`	`my-workspace`

Settings Object

Field	Type	Required	Description
`enabled`	boolean	No	Whether automated backup is enabled
`schedule`	string	No	Backup schedule name (see schedules)
`storage`	string	No	Storage location name (see storages)
`retention`	string	No	Retention policy: `Last 30 days`, `Last 90 days`, `Last 180 days`, `Last 360 days`

Response Data Model

Field	Type	Description
`platform`	string	The platform (`GitHub`, `AzureDevOps`, `GitLab`, or `Linear`)
`account`	string	The account or organization name
`backupSubjectName`	string	The name of the backup subject
`backupSubjectType`	string	The type: `Repository`, `Project`, or `Workspace` (Linear only)
`settings`	object	The current backup configuration

Error Responses

Status Code	Description
400 Bad Request	Invalid request format or parameters
401 Unauthorized	API key is missing or invalid
402 Payment Required	Plan limit exceeded
404 Not Found	Reserved for repository not found cases; in practice, account not found and definition not found errors are currently returned as `400 Bad Request`
422 Unprocessable Entity	Validation 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

Overview

Features

Prerequisites

API Reference

Get Backup Definition

GitHub Example

Azure DevOps Repository Example

Azure DevOps Project Example

GitLab Example

Linear Example

Response

Update Backup Definition

GitHub Example

Azure DevOps Example

GitLab Example

Linear Example

Response

Request Data Model

Subject Name Format

Settings Object

Response Data Model

Error Responses

Error Response Body

Backwards Compatibility

Platform-Specific Notes

GitHub

Azure DevOps

GitLab

Linear

References