Recording deployments

Using the New Relic REST API v2, you can record new deployments, retrieve a list of past deployments, and delete past deployments. Some agents also have agent-specific methods to record deployments automatically..

After recording deployments, you can view them in the Deployments page, and in the Recent Events list on the Overview page.

Access to this feature depends on your subscription level.

REST API procedures

You can use the New Relic REST API v2 to record deployments, get a list of past deployments, and delete deployments:

These examples below use cURL as a command line tool. However, you can use any method to make your REST requests. You can also create, view, and delete deployments with the API Explorer.

Record a deployment with POST

To record a new deployment, send a POST request that includes your REST API key to the deployments endpoint. Attach the payload in JSON format (see Character limits and JSON parameters). All payload parameters are optional except revision.

For example:

curl -X POST 'https://api.newrelic.com/v2/applications/${APP_ID}/deployments.json' \
     -H 'X-Api-Key:${API_KEY}' -i \
     -H 'Content-Type: application/json' \
     -d \
'{
  "deployment": {
    "revision": "REVISION",
    "changelog": "Added: /v2/deployments.rb, Removed: None",
    "description": "Added a deployments resource to the v2 API",
    "user": "datanerd@example.com"
  }
}' 

To record a deployment with PowerShell, send a POST request that includes your REST API key to the deployments endpoint. Attach the payload in JSON format (see Character limits and JSON parameters). All payload parameters are optional except revision.

This example uses PowerShell version 3 or higher:

Invoke-WebRequest -Uri http://api.newrelic.com/v2/applications/APP_ID/deployments.json -Method POST -Headers @{'X-Api-Key'='API_KEY'} -ContentType 'application/json' -Body '{
    "deployment": {
    "revision": "REVISION",
    "changelog": "Added: /v2/deployments.rb, Removed: None",
    "description": "Added a deployments resource to the v2 API",
    "user": "datanerd@example.com"
}
}'

This example uses PowerShell version 2 (requires .NET framework 3.5 or higher):

$encoding = [System.Text.Encoding]::GetEncoding("ASCII")
$data ='{
"deployment": {
    "revision": "REVISION",
    "changelog": "Added: /v2/deployments.rb, Removed: None",
    "description": "Added a deployments resource to the v2 API",
    "user": "datanerd@example.com"
}
}'
$postData = $encoding.GetBytes($data)
$request = [System.Net.WebRequest]::Create('https://api.newrelic.com/v2/applications/APP_ID/deployments.json')
$request.Method = 'POST'
$request.Headers.add('X-Api-Key','API_KEY')
$request.ContentType='application/json' 
$stream = $request.GetRequestStream()
$stream.Write($postData,0,$postData.Length)
$request.GetResponse()

To retrieve a list of all past deployments for your app, send a GET request that includes your REST API key to the deployments endpoint. GET requests do not use a JSON payload.

For example:

curl -X GET 'https://api.newrelic.com/v2/applications/${APP_ID}/deployments.json' \
    -H 'X-Api-Key:${API_KEY}' \
    -i
Sample output from GET

This example requests a list of deployments for app ID 9999999:

curl -X GET 'https://api.newrelic.com/v2/applications/9999999/deployments.json'  -H 'X-Api-Key:ABCDEFGHIJKLMNOPQRSTUVWXabcdefghijklmnopqrstuvwx'  -i

The API returns this list of deployments;

HTTP/1.1 200 OK
ETag: "ABCDEFGHIJKabcdefghijk0123456789"
Cache-Control: max-age=0, private, must-revalidate
Content-Type: application/json
{
  "deployments": [
    {
      "id": 1234567,
      "revision": "1234123412341234123412341234123412341234",
      "changelog": "Fixed the bugs for real this time",
      "description": "Example description two",
      "user": "Data Nerd",
      "timestamp": "2016-02-24T10:09:27-08:00",
      "links": {
        "application": 9999999
      }
    },
    {
      "id": 2345678,
      "revision": "7890789078907890789078907890789078907890",
      "changelog": "Think I fixed all the bugs",
      "description": null,
      "user": "Dren Atad",
      "timestamp": "2014-10-22T12:23:47-07:00",
      "links": {
        "application": 9999999
      }
    }
  ],
  "links": {
    "deployment.agent": "/v2/applications/{application_id}"
  }
}

To delete a deployment, send a DELETE request that includes your Admin User's API key to the deployments endpoint. DELETE requests do not use a JSON payload, but you must specify the ID for the deployment you want to delete. To retrieve the ID for a deployment, use the GET request.

For example:

curl -X DELETE 'https://api.newrelic.com/v2/applications/${APP_ID}/deployments/DEPLOYMENT_ID.json' \
     -H 'X-Api-Key:${ADMIN_USERS_KEY}' \
     -i
Character limits and JSON parameters

The JSON payload can include the following parameters:

Parameter Data Type Description
revision String, 127 character maximum Required. A unique ID for this deployment, visible in the Overview page and on the Deployments page. Can be any string, but is usually a version number or a Git checksum.
changelog String, 65535 character maximum Optional. A summary of what changed in this deployment, visible in the Deployments page when you select (selected deployment) > Change log.
description String, 65535 character maximum Optional. A high-level description of this deployment, visible in the Overview page and on the Deployments page when you select an individual deployment.
user String, 31 character maximum Optional. A username to associate with the deployment, visible in the Overview page and on the Deployments page.

Agent procedures

Some agents have additional methods to record deployments:

Partner account procedures

If you have an account through a New Relic partner, additional limitations or procedures may apply. For more information, refer to specific partner procedures:

For more help

Additional documentation resources include:

Join the discussion about New Relic APM in the New Relic Community Forum! The Community Forum is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.