Getting Started · Cohesity

Authentication based on Request & Response

Before making any API requests, the first step is always to make a "POST /public/accessTokens" request with valid Cohesity credentials. The REST API method uses this token based authentication. To get the access token:

A "Request" must be first sent to:
```
POST /public/accessTokens
```

The "Request body" must contain the Cohesity username and password:

{
  "password": "password",
  "username": "user",
  "domain": "LOCAL"
}

A successful "Response" looks like this: The accessToken from the response must be passed in the Authorization HTTP header of the subsequent requests.

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkb21haW4iOiJMT0NBTCIsImV4cGlyYXRpb24tdGltZSI6IjE1MzM0MDY0MjkiLCJzaWRzLWhhc2giOiJ2el91YlIwYTI5SDJ2NXFKRzdlbk9vdktPZGpzbjk2enk2NEFTeFZjSnVvIiwidXNlci1zaWQiOiJTLTEtMTAwLTIxLTgwNzY0NDMyLTU2MjI0MzkzLTEiLCJ1c2VybmFtZSI6ImFkbWluIn0.soQbj1Y18bbEPHQ84RdupGSLreaqywS7a3bBEe0nb90",
  "tokenType": "Bearer",
  "privileges": [
    "PRINCIPAL_VIEW",
    "CLUSTER_UPGRADE",
    "CLUSTER_EXTERNAL_TARGET_MODIFY",
    "PROTECTION_MODIFY",
    "PRINCIPAL_MODIFY",
    "CLONE_VIEW",
    "CLONE_MODIFY",
    "CLUSTER_MODIFY",
    "REMOTE_RESTORE",
    "STORAGE_VIEW",
    "REPORTS_VIEW",
    "CLUSTER_VIEW",
    "CLUSTER_SUPPORT",
    "PROTECTION_JOB_OPERATE",
    "PROTECTION_SOURCE_MODIFY",
    "RESTORE_VIEW",
    "RESTORE_MODIFY",
    "RESTORE_DOWNLOAD",
    "STORAGE_MODIFY",
    "ANALYTICS_VIEW",
    "PROTECTION_VIEW",
    "ANALYTICS_MODIFY",
    "MCM_MODIFY",
    "GDPR_VIEW"
  ]
}

The accessToken from the response must be passed in the Authorization HTTP header of the subsequent requests. Note: The generated token is valid for 24 hours. If a request is made with an expired token, the 'Token expired' error message is returned.

Common Workflows

The below section provides examples to demonstrate the sequence of APIs that must be called for specific scenarios.

Consider the scenario to Recover a VM (VMware). To do this, the sequence of APIs to be called is as follows:

Create/Register a Protection Source. Once the VMware source is registered, its objects (VMs) are eligible to be protected, backed up or recovered on the Cohesity cluster.
Create a Protection Policy. A protection job uses the schedules and settings defined in the policy to determine when and how backups are captured, archived or replicated.
List Storage Domains.
Create a Protection Job. In order to recover VMs, you must first create snapshots using this step.
Recover a VM. You can recover VMs from a snapshot created in the protection job. You can recover VMs to their original or a new location.

Register Protection Sources

You must register a source that needs to be protected or backed up on a Cohesity cluster. For example: Consider a VMware vCenter Server to be registered as a source so that its VMs are eligible to be backed up.

Create a POST request to register a protection source (vCenter).

curl -X POST \
  --url 'https://{{cluster}}/irisservices/api/v1/public/protectionSources/register' 
  -H 'Authorization: Bearer {TOKEN}'\
  -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  --data-raw '{}'

Pass the following parameters in the request body of the endpoint.

Parameter	Description
endpoint	Specifies the agent endpoint if it is different from the source endpoint.
environment	Specifies the environment of the protection source. Example: kVMware , which indicates the indicates the VMware Protection Source environment.
username	Specifies username to access the target source.
password	Credentials to authenticate.
vmwareType	Specifies the entity type such as 'kVCenter' if the environment is kKMware.

Example:

{
  "endpoint": "vcenter.domain.com",
  "environment": "kVMware",
  "username": "username",
  "password":"password",
  "vmwareType": "kVCenter"
}

If you have already registered the protection source, you can use the below GET method to retrieve the list of already registered protection sources.
```
https://{{cluster}}/irisservices/api/v1/public/protectionSources/rootNodes
```

On sending the request, the Cohesity REST API returns the newly registered Protection Source on success.

[
    {
        "protectionSource": {
            "id": 1,
            "name": "TestStorage",
            "environment": "kView",
            "viewProtectionSource": {
                "type": "kViewBox",
                "name": "TestStorage",
                "id": {
                    "id": 29955,
                    "clusterId": 1234567890,
                    "clusterIncarnationId": 123454242332
                }
            }
        },
        "protectedSourcesSummary": [
            {
                "environment": "kView"
            }
        ],
        "unprotectedSourcesSummary": [
            {
                "environment": "kView",
                "leavesCount": 1,
                "totalLogicalSize": 1523634514
            }
        ],
        "registrationInfo": {
            "accessInfo": {},
            "registrationTimeUsecs": 1560407608539235,
            "refreshTimeUsecs": 1575253040545122,
            "authenticationStatus": "kFinished"
        }
    },
    ...
]

Create Protection Policy

To define the settings that will be used by the protection job to run, we must first create a protection policy as follows:

Create a POST request as follows:

https://{{cluster}}/irisservices/api/v1/public/protectionPolicies

In the Request body, configure the below parameters to specify the schedules and other settings that will be reused by the protection job.

Parameter	Description
description	Description of the Protection Policy.
fullSchedulingPolicy	Specifies settings that define a backup schedule for a Protection Job.
name	Specifies the name of the Protection Policy.
systemSchedulingPolicy	Specifies the settings that define a backup schedule for a Protection Job.
type	Specifies the type of the protection policy. 'kRegular' means a regular Protection Policy. 'kRPO' means an RPO Protection Policy.

On sending the request, the Cohesity REST API returns the newly registered Protection Policy ID.

 [
 {
   "id": "1234567890:123456785444:1",
   "name": "Gold",
   "123454242332": {
     "periodicity": "kContinuous",
     "continuousSchedule": {
       "backupIntervalMins": 240
     }
   },
   "extendedRetentionPolicies": [
     {
       "periodicity": "kDay",
       "multiplier": 1,
       "daysToKeep": 90
     },
     {
       "periodicity": "kWeek",
       "multiplier": 1,
       "daysToKeep": 365
     },
     {
       "periodicity": "kMonth",
       "multiplier": 1,
       "daysToKeep": 1096
     }
   ],
   "retries": 2,
   "retryIntervalMins": 10,
   "daysToKeep": 7
 }
 ...
 ]

List Storage Domains

A Storage Domain contains of views. When you configure a Protection Job, you must specify a Storage Domain, that is the location where the Cohesity cluster stores the Snapshots.

Create a GET request as follows:

https://{{cluster}}/irisservices/api/v1/public/viewBoxes

On sending the request, the Cohesity REST API returns the list of storage domains created.

[
    {
        "id": 18,
        "name": "DefaultStorageDomain",
        "clusterPartitionId": 16,
        "storagePolicy": {
            "deduplicationEnabled": true,
            "inlineDeduplicate": true,
            "compressionPolicy": "kCompressionLow",
            "inlineCompress": true,
            "deduplicateCompressDelaySecs": 0,
            "encryptionPolicy": "kEncryptionNone",
            "numFailuresTolerated": 1,
            "numNodeFailuresTolerated": 1
        },
        "s3BucketsAllowed": false,
        "adDomainName": null,
        "ldapProviderId": null,
        "clusterPartitionName": "DefaultPartition",
        "removalState": "kDontRemove"
    },
    ...
]

Create a Protection Job

You can create a protection job that runs repeatedly, based on an associated policy, to back up data from a source and store it on the cluster. To create a protection job, you must first define the Protection Policy which is a set of reusable settings that defines how and when objects are protected, replicated and archived.

Example: The following example provides the steps to create a protection job with a VMware protection source.

Create a POST request as follows:

https://{{cluster}}/irisservices/api/v1/public/protectionJobs

In the Request body, specify the required parameters to register a protection source.

Parameter	Description
name	Name of the protection job.
policyId	Specifies the unique id of the Protection Policy associated with the Protection Job.
viewBoxID	Specifies the Storage Domain (View Box) id where this Job writes data.
environment	Specifies the environment type (such as kVMware or kSQL) of the Protection Source this Job is protecting.
sourceIDs	Specifies the list of Object ids from the Protection Source to protect (or back up) by the Protection Job.
parentsourceId	Specifies the ID of the registered Protection Source that is the parent of the objects that may be protected by this Job.

Example:

 {
     "policyId": "1234567890:123456785444:1",
     "viewBoxId": 1234567,
     "123454242332": "kVMware",
     "sourceIds": [
       1856
     ],
     "parentSourceId": {{parentSourceId}},
     "excludeSourceIds": [],
     "isNew": true,
     "indexingPolicy": {
       "disableIndexing": false,
       "allowPrefixes": [
         "/"
       ],
       "denyPrefixes": [
         "/$Recycle.Bin",
         "/Windows",
         "/Program Files",
         "/Program Files (x86)",
         "/ProgramData",
         "/System Volume Information",
         "/Users/*/AppData",
         "/Recovery",
         "/var",
         "/usr",
         "/sys",
         "/proc",
         "/lib",
         "/grub",
         "/grub2"
       ]
     }
 }

On sending the request, the Cohesity REST API returns the newly protection job ID.

{
  "name": "TestNow",
  "policyId": "1234567890:123456785444:1",
  "_policyName": "Gold",
  "123454242332": 18,
  "_viewBoxName": "DefaultStorageDomain",
  "timezone": "Asia/Kolkata",
  "environment": "kVMware",
  "sourceIds": [
    46
  ],
  "parentSourceId": 35,
  "excludeSourceIds": [],
  "isNew": true,
  "indexingPolicy": {
    "disableIndexing": false,
    "allowPrefixes": [
      "/"
    ],
    ...

Verify Protection Job Status

You can force execute a single job run and ignore the schedule that is defined in the Policy or allow the job to run at the specified run time.

To run a protection job, create an execute protection job request as follows.

https://{{cluster}}/irisservices/api/v1/public/protectionJobs/run/{{protectionJobId}}

Specify the parameters to run the job as follows:

{
  "copyRunTargets": null,
  "runNowParameters": null,
  "runType": null,
  "sourceIds": null
}

Returns success if the Job Run starts.

To verify the status of the protection job, create a GET request as follows:
```
https://{{cluster}}/irisservices/api/v1/public/protectionRuns
```

On sending the request, the Cohesity REST API returns the status of the job run.

[
    {
        "jobName": "TestNow",
        "jobId": 12345,
        "jobUid": {
            "id": 12345,
            "clusterId": 1234567890,
            "clusterIncarnationId": 123454242332
        },
        "viewBoxId": 18,
        "backupRun": {
            "runType": "kRegular",
            "environment": "kVMware",
            "jobRunId": 72925,
            "stats": {
                "startTimeUsecs": 1575263728435271,
                "totalSourceSizeBytes": 53687091200,
                "totalBytesReadFromSource": 0,
                "totalLogicalBackupSizeBytes": 0,
                "totalPhysicalBackupSizeBytes": 0,
                "numSuccessfulAppObjects": 0,
                "numSuccessfulTasks": 0,
                "numFailedTasks": 1,
                "numCanceledTasks": 0
            },
            "status": "kAccepted",
            "sourceBackupStatus": [
              ...

Recover a VM

Cohesity provides the ability to recover Protected Objects (such as VMs) from a Snapshot created earlier by a Protection Job. You can recover VMs from a Cohesity cluster or a currently registered archive. You can recover VMs to their original location or a new location.

Example : This example provides the steps to recover VMs.

Create a Recover VM POST request as follows to create a Restore Task for recovering VMs or mounting volumes to mount points. :
```
https://{{cluster}}/irisservices/api/v1/public/restore/recover
```

Specify the parameters to create a Restore task for recovering VMs.

Parameter	Description
name	Specifies the name of the Restore Task.
type	Specifies the type of Restore Task. In this case, the value must be kRecoverVMs.
vmwareParameters	Specifies the information required for recovering or cloning VmWare VMs.

On sending the request, the Cohesity REST API returns success.

{
    "id": 1234,
    "type": "kRecoverVMs",
    "status": "kReadyToSchedule",
    "username": "admin",
    "startTimeUsecs": 1575264894158097,
    "fullViewName": "cohesity_int_1234_2a5cb",
    "viewBoxId": 1234567,
    "targetViewCreated": true,
    "name": "Restore-VCD-VMs-1",
    "objects": [
        {
            "jobUid": {
                "id": 67663,
                "clusterId": 1234567890,
                "clusterIncarnationId": 123454242332
            },
            "jobRunId": 12345,
            "startedTimeUsecs": 1575006454683153,
            "protectionSourceId": 1234
        }
    ],
    "newParentId": 1111,
    "prefix": "new",
    "suffix": "vm",
    "poweredOn": false,
    "continueOnError": true,
    "vmwareParameters": {}
}

Cluster APIs

Visit the Versions Page to refer to the Cohesity Cluster APIs for various releases