Operations API
Learn how to manage Cloudback backup definitions programmatically using the Operations API for automated backup configuration across supported platforms.
AutomationOverview
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
isEnabledandstate: automated backups needisEnabled: trueandstate: CanBackupAndRestore. You can also check disabled or restore-only backups. - Look at
itemsfor the latest backups, newest first.Succeeded,Failed,QueuedandInProgresshelp you spot a recent success, failure or pending run. An empty list means no backup history is available. - Use
triggerTypeto distinguishScheduledandManualbackups.Undefinedmeans the trigger is unknown. - All times are in UTC.
queueTimeUtcrecords when the backup was queued;startTimeUtccan change when a backup starts or is retried. For a queued backup, it does not mean work has started.endTimeUtccan 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
| 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
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 namesubjectName: Repository namesubjectType: AlwaysRepository
Azure DevOps
account: Azure DevOps organization namesubjectName: For repositories useproject/repositoryformat; for projects use just the project namesubjectType: UseRepositoryfor repository backups,Projectfor project-level backups- Ensure the Azure DevOps organization has Cloudback authorized
GitLab
account: GitLab group name or personal namespacesubjectName: Project namesubjectType: AlwaysProject
Linear
account: Linear workspace key (the short identifier for the workspace)subjectName: Linear workspace namesubjectType: AlwaysWorkspace- Each Linear workspace is backed up as a single unit; the
Workspacesubject type is unique to Linear