Deployment API

Opsgenie's deployment API can be used to perform deployment-related actions with the Investigate an incident feature which allows you to track your deployments leading up to, and during incidents. These deployments will contain commit information from the SCM tool that you connect with your Bitbucket account. Currently, Opsgenie supports only Bitbucket cloud as the SCM tool of choice. Therefore please ensure that before using the deployment API you have configured the Opsgenie with Bitbucket Cloud and have mapped your Bitbucket repositories to your Opsgenie services.

📘
Create an API Integration and obtain your apiKey to make requests listed below.

🚧
If using the EU instance of Opsgenie, the URL needs to be https://api.eu.opsgenie.com for requests to be successful.

Get Request Status

Deployment creation and update requests are processed asynchronously to provide higher availability and scalability. Therefore valid requests for those endpoints are responded with HTTP status 202 - Accepted. Get Request Status endpoint is used to track the status and deployment details (if any) of the request whose identifier is given.

HTTP Method	URL
GET	https://api.opsgenie.com/v2/deployments/requests/:requestId

In-Line Parameters

Referred Name	Description
requestId	Universally unique identifier of the questioned request. Please note: that ID of the request was provided within the response.

Get Deployment

HTTP Method	URL
GET	http://api.opsgenie.com/v2/deployments/:identifier

In-Line Parameters

Referred Name	Description
identifier	Deployment identifier to specify which deployment to update.

Query Parameters

Parameter	Mandatory	Description
type	false	Deployments can be identified with the deployment id returned in the response after deployment is created. However you may also refer to deployments using an external id or Bitbucket Pipelines UUID if Bitbucket Pipelines is being used as the deployment tool. In that case specify the type as api or pipelines respectively.

Sample Request

curl --location --request GET 'http://api.opsgenie.com/v2/deployments/2b70a31e-90f0-3d1e-869c-b2cf27762464' \
-H 'Authorization: GenieKey e3cfa715-725d-49de-95cb-4fd18c878ag8'

curl --location --request GET 'http://api.opsgenie.com/v2/deployments/2b70a31e-90f0-3d1e-869c-b2cf27762464?type=api' \
-H 'Authorization: GenieKey e3cfa715-725d-49de-95cb-4fd18c878ag8'

curl --location --request GET 'http://api.opsgenie.com/v2/deployments/2b70a31e-90f0-3d1e-869c-b2cf27762464?type=pipelines' \
-H 'Authorization: GenieKey e3cfa715-725d-49de-95cb-4fd18c878ag8'

Sample Responses
There are two kinds of responses depending on whether the deployment tool is Atlassian's Bitbucket Pipeline or some third party tool. To use Bitbucket Pipelines along with Opsgenie read how to connect your Bitbucket workspaces to your Opsgenie account.

Deployments performed using Bitbucket Pipelines

{
    "data": {
        "id": "2b70a31e-90f0-3d1e-869c-b2cf27762464",
        "externalId": "{e4daecfb-9d84-5711-b49d-eae11a99d3e9}",
        "state": "successful",
        "environment": {
            "environmentType": "Production",
            "identifier": "{e5cfd278-1d21-47f2-bd64-423ea00fdd60}",
            "displayName": "production"
        },
        "type": "pipelines",
        "startedAt": "2020-03-26T14:05:07.594Z",
        "completedAt": "2020-03-26T14:15:07.594Z",
        "releases": [
            {
                "commit": {
                    "sha": "eb6d685a958183108588a8a91846fad3568b1bd5"
                },
                "type": "bbc",
                "repository": {
                    "repoSlug": "{33838c22-5066-425e-8a23-4a6699011119}",
                    "workspace": "{0a4fb641-0c65-44ab-bb4f-64a44bada7be}"
                }
            }
        ],
        "createdOn": "1970-01-01T00:26:23.273Z",
        "fullname": "opsgenie-plugin-test-1/opsgenie-notification-repository",
        "deployableName": "Owner or admin can delete the forwarding rule for everybody",
        "commitMessage": "Owner or admin can delete the forwarding rule for everybody"
    },
    "took": 0.051,
    "requestId": "a44339cf-ea48-42d5-bb09-d67b392674e8"
}

Deployments performed using other deployment tools

{
    "data": {
        "id": "7b25450b-c668-4eb4-b75c-77333ca1ada7",
        "externalId": "7b25450b-c668-4eb4-b75c-77333ca1ada7",
        "state": "successful",
        "environment": {
            "environmentType": "Test",
            "identifier": "og-test",
            "displayName": "og-test"
        },
        "type": "api",
        "startedAt": "2020-03-26T14:05:07.594Z",
        "completedAt": "2020-03-26T14:15:07.594Z",
        "releases": [
            {
                "commit": {
                    "sha": "0c9135c"
                },
                "type": "bbc",
                "repository": {
                    "repoSlug": "kagan-test-repo5",
                    "workspace": "saltbae-test"
                }
            }
        ],
        "message": "kagan-test"
    },
    "took": 5.134,
    "requestId": "6d50765f-7aae-44c2-bf8e-03cefedd2dfb"

Create Deployment

HTTP Method	URL
POST	https://api.opsgenie.com/v2/deployments/

JSON Body Fields

Field	Mandatory	Description
state	true	Deployment state which can be any one of the following: `initial` `started` `successful` `failed`
environment	true	Depicts the environment in which the artifact was deployed. It contains the three fields where the type field can be any one of the values below: `Test` `Staging` `Production` The three values of the type* field are for environment categorization purposes*
startedAt	true	Date and time of when the deployment has begun
completedAt	false	Date and time of the completion of the deployment.
message	false	The deployment message
externalId	false	An identifier of the deployment other than that which will be created by the Opsgenie API upon completion of the Create request
description	false	Description of the deployment
externalLink	false	URL that links the deployment created within Opsgenie to the deployment in the deployment tool used
releases	true	Contians artifact information along with commits included which originate from the SCM tool of choice Check out the list of SCM tools supported for the specific fields contained under releases.

enviornment field example:

"environment": {
  "type": "Test",
    "id": "us-west-2",
      "displayName": "Lab Oregon"
}

releases field example:
Check the SCM-specific fields here.

"releases": [
  {
    "type": "bbc",
    "repository": {
      "workspace": {
        "identifier": "opsgenie"
      },
      "repoSlug": "opsgenie-integration"
    },
    "commit": {
      "sha": "61445f308944af8f665326c29c02f16a4c3b0019"
    }
  }
]

Sample Payload

{
  "state": "started",
  "environment": {
    "type": "Test",
    "id": "us-west-2",
    "displayName": "Lab Oregon"
  },
  "startedAt": "2020-03-26T14:05:07.594Z",
  "completedAt": "2020-03-26T14:15:07.594Z",
  "message": "Hotfix for integration",
  "externalId": "2153ff23a294428ace87a89846699f35",
  "description": "Changed node types with versions: resource-deploy-RELEASE-20200323033142, api-RELEASE-20200323033142, devops-RELEASE-20200323033142, ",
  "reference": "http://jenkins.myownci.com//#/trace/2153ff23a294428ace87a89846699f35",
  "releases": [
    {
      "type": "bbc",
      "repository": {
        "workspace": {
          "identifier": "myownci"
        },
        "repoSlug": "myownci-integration"
      },
      "commit": {
        "sha": "61445f248943ag8a65346c29c03f16a4c3b0019"
      }
    }
  ]
}

Sample Request

curl --location --request POST 'https://api.opsgenie.com/v2/deployments' \
-H 'Content-Type: application/json' \
-H 'Authorization: GenieKey 5eebf5f6-7de1-454d-a590-ea3b271e8919' \
-d '{"state":"started","environment":{"type":"Test","id":"us-west-2","displayName":"Lab Oregon"},"startedAt":"2020-03-26T14:05:07.594Z","message":"Hotfix for integration","externalId":"2153ff23a294428ace87a89846699f35","description":"Changed node types with versions: resource-deploy-RELEASE-20200323033142, api-RELEASE-20200323033142, devops-RELEASE-20200323033142, ","reference":"http://jenkins-myownci.com/#/trace/2153ff23a294428ace87a89846699f35","releases":[{"type":"bbc","repository":{"workspace":{"identifier":"myownci"},"repoSlug":"myownci-integration"},"commit":{"sha":"61445f308944af8f665326c29c02f16a4c3b0019"}}]}'

Sample Response

📘
Createdeployment requests are processed asynchronously, therefore valid requests are responded with HTTP status 202 - Accepted.

{
    "result": "Request will be processed",
    "took": 0.302,
    "requestId": "43a23c5c-35bf-4ea4-9c26-a4f71023e120"
}

However, once getting the async response by using the Get Request Status operation either one of the responses below is expected, depending on whether the deployment has been successfully created or not.

Deployment creation is successful:

{
    "data": {
        "action": "Create",
        "processedAt": "2020-04-27T12:47:50.866Z",
        "isSuccess": true,
        "status": "Deployment successfully created",
        "deploymentId": 5asdb4d8-6615-43c5-8613-c29f12bb630b"
    },
    "took": 4.888,
    "requestId": "7725b4d8-6619-43c5-8413-c29fd1bb630b"
}

Deployment creation is unsuccessful:

{
    "data": {
        "action": "Create",
        "processedAt": "2020-04-27T12:47:50.866Z",
        "isSuccess": false,
        "status": "Bitbucket Integration with name: opsgenie not found",
        "deploymentId": ""
    },
    "took": 4.888,
    "requestId": "7725b4d8-6619-43c5-8413-c29fd1bb630b"
}

Update Deployment Status

HTTP Method	URL
PATCH	https://api.opsgenie.com/v2/deployments/:identifier/updateState

In-Line Parameters

Referred Name	Description
identifier	Deployment identifier to specify which deployment to update.

Query Parameters

Parameter	Mandatory	Description
type	false	Deployments can be identified with the deployment id returned in the response after deployment is created. However you may also refer to deployments using an external id or Bitbucket Pipelines UUID if Bitbucket Pipelines is being used as the deployment tool. In that case specify the type as api or pipelines respectively.

JSON Body Fields

Field	Mandatory	Description
state	true	Deployment state which can be any one of the following: `initial` `started` `successful` `failed`
completedAt	true	Date and time of the completion of the deployment, or update of deployment state.

Sample Requests

curl --location --request PATCH 'https://api.opsgenie.com/v2/deployments/7b25450b-c668-4eb4-b75c-77333ca1ada7/updateState' \
-H 'Content-Type: application/json' \
-H 'Authorization: GenieKey 5eebfrf6-7we1-464d-a190-ea33271e4959' \
-d '{
	"state": "successful",
	"completedAt": "2019-11-07T14:44:02.374Z"
}'

curl --location --request PATCH 'https://api.opsgenie.com/v2/deployments/7b25450b-c668-4eb4-b75c-77333ca1ada7/updateState?type=api' \
-H 'Content-Type: application/json' \
-H 'Authorization: GenieKey 5eebfrf6-7we1-464d-a190-ea33271e4959' \
-d '{
	"state": "successful",
	"completedAt": "2019-11-07T14:44:02.374Z"
}'

Sample Response

📘
Update deployment requests are processed asynchronously, therefore valid requests are responded with HTTP status 202 - Accepted.

{
    "result": "Request will be processed",
    "took": 0.302,
    "requestId": "43a23c5c-35bf-4ea4-9c26-a4f71023e120"
}

However once getting the async response by using the Get Request Status operation the response below is expected.

{
    "data": {
        "action": "Update State",
        "processedAt": "2020-04-27T12:47:50.866Z",
        "isSuccess": true,
        "status": "Deployment State updated successfully",
        "deploymentId": 5asdb4d8-6615-43c5-8613-c29f12bb630b"
    },
    "took": 4.888,
    "requestId": "7725b4d8-6619-43c5-8413-c29fd1bb630b"
}

Update deployment

🚧
The Update endpoint is not compatible for Bitbucket pipeline deployments.

HTTP Method	URL
PATCH	https://api.opsgenie.com/v2/deployments/:identifier/update

In-Line Parameters

Referred Name	Description
identifier	Deployment identifier to specify which deployment to update.

Query Parameters

Parameter	Mandatory	Description
type	false	Deployments can be identified with the deployment id returned in the response after deployment is created. .

JSON Body Fields

Field	Mandatory	Description
externalLink	false	URL that links the deployment created within Opsgenie to the deployment in the deployment tool used
description	false	Description of the deployment
message	false	The deployment message
externalId	false	An identifier of the deployment other than that which will be created by the Opsgenie API upon completion of the Create request
startedAt	false	Date and time of when the deployment has begun

Sample Request

curl -X PATCH \
  https://api.opsgenie.com/v2/deployments/80bb7f79-a730-4c10-a566-fd99023fc03b/update \
  -H 'authorization: GenieKey 422f0f3c-788b-7e0e-a8d7-93c7ec5bf2e8' \
  -H 'content-type: application/json' \
  -d '{
	"externalLink": "http://demo.in",
	"description": "test_description",
	"message": "test_message",
	"externalId": "test_externalId",
	"startedAt": "2020-08-07T14:44:02.374Z"
}'

Sample Response

📘
Update deployment requests are processed asynchronously, therefore valid requests are responded with HTTP status 202 - Accepted.

{
    "result": "Request will be processed",
    "took": 0.302,
    "requestId": "43a23c5c-35bf-4ea4-9c26-a4f71023e120"
}

However once getting the async response by using the Get Request Status operation the response below is expected.

{
    "data": {
        "action": "Update",
        "processedAt": "2020-04-27T12:47:50.866Z",
        "isSuccess": true,
        "status": "Deployment updated successfully",
        "deploymentId": 5asdb4d8-6615-43c5-8613-c29f12bb630b"
    },
    "took": 4.888,
    "requestId": "7725b4d8-6619-43c5-8413-c29fd1bb630b"
}

Search Deployments

HTTP Method	URL
GET	https://api.opsgenie.com/v2/deployments/search

Query Parameters

Parameter	Mandatory	Type	Description
serviceIds	true	Set<String>	A list of services to which the required deployments are mapped
environmentIds	false	Set<String>	Acts as a filter parameter to search for deployments within specific environments
startTime	false	@DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME)	Acts as a filter parameter to search on specific deployment start times
endTime	false	@DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME)	Acts as a filter parameter to search on specific deployment end times
paginationKey	false	Integer	Acts as the start index when returning a list of results in a paginated manner
limit	false	Integer	Allows to limit the number of search results

Sample Requests

curl --location --request GET 'https://api.opsgenie.com/v2/deployments/search?serviceIds=96f6655c-73f1-4d4b-a1a5-4b97dd8409b5&limit=10' \
--header 'Authorization: GenieKey a85cfdbf-3f6b-4ca4-a81b-2fe83da4fcbd' \
--header 'Content-Type: application/json'

Sample Response

{
   "data":[
      {
         "id":"0e1a5c8d-66a5-34a4-a315-733caa5e5636",
         "externalId":"{4d1cd861-99be-5708-9925-e4e153365098}",
         "type":"pipelines",
         "state":"successful",
         "startedAt":"2020-08-17T08:16:57.943Z",
         "completedAt":"2020-08-17T08:17:02.998Z",
         "message":"Deployment #5",
         "description":"2f5e052 Adding README123.md\n",
         "environment":{
            "type":"Production",
            "id":"{598f7ddd-21c3-4064-a569-4dac1b8b0280}",
            "displayName":"production"
         }
      },
      {
         "id":"a076ca38-a202-344c-afe0-c0b13baf51e5",
         "externalId":"{a5671456-6ebf-5bb5-a546-5ba44f480bf2}",
         "type":"pipelines",
         "state":"successful",
         "startedAt":"2020-08-07T04:55:56.815Z",
         "completedAt":"2020-08-07T04:56:01.439Z",
         "message":"Deployment #3",
         "description":"e20e4b7 Initial Bitbucket Deployments configuration",
         "environment":{
            "type":"Production",
            "id":"{598f7ddd-21c3-4064-a569-4dac1b8b0280}",
            "displayName":"production"
         }
      },
      {
         "id":"29a25632-1189-37ca-ae7b-8828e77ab077",
         "externalId":"{cf848148-506d-52ff-b909-9ec2d8312591}",
         "type":"pipelines",
         "state":"successful",
         "startedAt":"2020-08-17T08:11:33.326Z",
         "completedAt":"2020-08-17T08:11:37.91Z",
         "message":"Deployment #4",
         "description":"54135bc Adding readme file\n",
         "environment":{
            "type":"Production",
            "id":"{598f7ddd-21c3-4064-a569-4dac1b8b0280}",
            "displayName":"production"
         }
      }
   ],
   "took":4.448,
   "requestId":"3784efa6-fb53-4099-9ba6-5e71fc5f86d6"
}

SCM-Specific Fields

📘
Currently, Opsgenie only supports Bitbucket Cloud as the SCM tool managing the code base included in the artifacts deployed by the deployment tool of your choice. The deployment API allows you to capture deployments made by your preferred deployment tools. Hence before using the API, please connect your Bitbucket workspaces to your Opsgenie account and map your Bitbucket repositories to your Opsgenie services accordingly.

Bitbucket Cloud

Field	Mandatory	Description	Limit
type		Value should be `bbc` to set SCM tool holding release codebase as Bitbucket cloud
repository		Consists of two fields which are the workspace field and repoSlug which refer to the Bitbucket workspace and the specific repo within the workspace respectively. While referring your workspaces you can either type your workspace name or you can use UUID of the workspace as identifier and add type attribute with bbcUuid as it's value.
commit		The commit included in the release

Sample Payload

"releases": [
    {
      "type": "bbc",
      "repository": {
        "workspace": {
          "identifier": "opsgenie"
        },
        "repoSlug": "opsgenie-integration"
      },
      "commit": {
        "sha": "61445f308944af8f665326c29c02f16a4c3b0019"
      }
    },
    {
      "type": "bbc",
      "repository": {
        "workspace": {
          "identifier": "opsgenie"
        },
        "repoSlug": "opsgenie-apps"
      },
      "commit": {
        "sha": "61445f30894asdasdf665326c29c02f16a4c3b0019"
      }
    }
  ]