# 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 * [MCP Server](https://docs.cloudback.it/automation/mcp-server) * [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) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cloudback.it/automation/operations-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.