# Operations API ## 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](https://app.cloudback.it/apikeys) 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 ```http 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 ```http 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 ```http 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 ```http 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 ```http 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 ```json 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 ```http 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 ```http 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 ```http 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 ```http 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 ```json 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](https://app.cloudback.it/schedules)) | | `storage` | string | No | Storage location name (see [storages](https://app.cloudback.it/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. ```json "Account not found" ``` For 402 Payment Required, the response uses the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) Problem Details format: ```json { "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`. ```http # 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 * [Terraform Provider](https://docs.cloudback.it/automation/terraform-provider) * [GitHub Installation Guide](https://docs.cloudback.it/github/installation-guide) * [Azure DevOps Installation Guide](https://docs.cloudback.it/azure-devops/installation-guide) * [Linear Installation Guide](https://docs.cloudback.it/linear/installation-guide) * [GitLab Installation Guide](https://docs.cloudback.it/gitlab/installation-guide)