--- title: Record and view deployments source: https://docs.newrelic.com/docs/apm/apm-ui-pages/events/record-deployments --- > #### ⚠️ THE REST API FOR DEPLOYMENTS IS REACHING END OF LIFE > > The REST API v2 deployment endpoints (`/v2/applications/{app_id}/deployments.json`) documented on this page, along with the legacy Deployments v0 API, [reach end of life on July 31, 2027](/eol/2026/07/eol-07-31-26-rest-api-v2). After that date, they won't be available. > > Record deployments with the [change tracking](https://docs.newrelic.com/docs/change-tracking/overview/) feature instead, using the NerdGraph `changeTrackingCreateEvent` mutation. For endpoint-by-endpoint mappings, see the [Migrate from REST API v2 to NerdGraph](https://docs.newrelic.com/docs/apis/rest-api-v2/migrate-to-nerdgraph/#deployments) guide. The REST instructions below remain as reference for existing integrations you're migrating. > #### 💡 TIP > > Change tracking is available for APM, browser monitoring, and mobile monitoring. Deploying an app can be a risky event—when your app breaks, and a bad deployment is often the cause. New Relic allows you to track deployments so you can correlate deployments with changes in your app's performance. Tracking deployments creates deployment markers that appear in APM charts and dashboards. See how deployment markers work in this short video (4:30 minutes): ## Options for tracking deployments [#options] You can record new deployments and retrieve a list of past deployments with either the New Relic [REST API v2](https://docs.newrelic.com/docs/apis/rest-api-v2/requirements/new-relic-rest-api-v2-getting-started) or [NerdGraph](https://docs.newrelic.com/docs/change-tracking/config/nerdgraph/). Use NerdGraph: the REST API v2 deployment endpoints [reach end of life on July 31, 2027](/eol/2026/07/eol-07-31-26-rest-api-v2). Additionally, some APM agents offer agent-specific methods to automatically record deployments. You can use your [Slack](https://slack.com/) integration with New Relic, or a simple webhook, to notify your team in real time of deployments for applications monitored by APM. Slack provides a webhook URL that allows you to post generic JSON that will appear formatted in a chosen Slack channel. There are a few places where you can view deployments in the New Relic UI after they have been recorded: - In the activity feed on the [APM Summary](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/apm-overview-page-view-transaction-apdex-usage-data), Service summary, and [entity summary pages](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/ui-data/new-relic-one-entity-explorer-view-performance-across-apps-services-hosts). - On APM performance charts as chart markers (vertical lines with pinheads). - On dashboard charts as chart markers. - On the [Deployments](https://docs.newrelic.com/docs/apm/applications-menu/events/deployments-page-view-impact-your-app-users) page for summary performance. > #### 💡 TIP > > Deployment markers are not available for browser applications, but you can try these alternatives: > > - Switch from deployment markers to the [change tracking](https://docs.newrelic.com/docs/change-tracking/change-tracking-introduction) feature that enables you to track browser application changes. > - See [browser releases](https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-spa-api/add-release) for a way to tag errors with release versions. ## Record deployments with the REST API [#api-instructions] > #### ⚠️ THESE REST ENDPOINTS REACH END OF LIFE JULY 31, 2027 > > The REST API v2 deployment endpoints shown below [reach end of life on July 31, 2027](/eol/2026/07/eol-07-31-26-rest-api-v2) and will stop working after that date. Migrate to the NerdGraph `changeTrackingCreateEvent` mutation, see the [Migrate from REST API v2 to NerdGraph](https://docs.newrelic.com/docs/apis/rest-api-v2/migrate-to-nerdgraph/#deployments) guide. These instructions remain for reference while you migrate existing integrations. You can use the New Relic REST API v2 to record deployments and get a list of past deployments. - The examples in this document use `curl` as a command-line tool. However, you can use any method to make your REST requests. You can also create and view deployments with the [API Explorer](https://api.newrelic.com/docs/#/Applications/post_applications__application_id__deployments_json). - JSON uses double quotes `"` for element names and content. Using single quotes `'` will cause errors. - The examples use `X-Api-Key` which can be used for either a user key or a REST API key. User keys are now the preferred way of accessing our REST APIs, and you may use `Api-Key` headers when using them. **Record a deployment with POST** To record a new deployment, send a `POST` request that includes your [API key](https://docs.newrelic.com/docs/apis/rest-api-v2/getting-started/introduction-new-relic-rest-api-v2#api_key) to the deployments endpoint. Attach the payload in JSON format (see [Character limits and JSON parameters](#deployment_limits)). All payload parameters are optional except `revision`. For example: ````bash 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", "timestamp": "2019-10-08T00:15:36Z" } }' ``` ```` **Record a deployment with PowerShell** To record a deployment with PowerShell, send a `POST` request that includes your [API key](https://docs.newrelic.com/docs/apis/rest-api-v2/getting-started/introduction-new-relic-rest-api-v2#api_key) to the deployments endpoint. Attach the payload in JSON format (see [Character limits and JSON parameters](#deployment_limits)). All payload parameters are optional except `revision`. This example uses PowerShell version 3 or higher: ````powershell Invoke-WebRequest -Uri https://api.newrelic.com/v2/applications/YOUR_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", "timestamp": "2019-10-08T00:15:36Z" } }' ``` This example uses PowerShell version 2 (requires .NET framework 3.5 or higher): ```powershell $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", "timestamp": "2019-10-08T00:15:36Z" } }' $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() ``` ```` **View a list of deployments with GET** To retrieve a list of all past deployments for your app, send a `GET` request that includes your [API key](https://docs.newrelic.com/docs/apis/rest-api-v2/getting-started/introduction-new-relic-rest-api-v2#api_key) to the deployments endpoint. GET requests do not use a JSON payload. For example: ````bash curl -X GET "https://api.newrelic.com/v2/applications/$APP_ID/deployments.json" \ -H "X-Api-Key:$API_KEY" \ -i ``` This example requests a list of deployments for app ID `9999999`: ```bash 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: ```json 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}" } } ``` ```` **Character limits and JSON parameters** The JSON payload can include the following parameters. > #### ⚠️ IMPORTANT > > UTF-8 4 byte characters, such as Emojis and some non-Latin language glyphs, cannot be used in the deployment text. | Parameter | Data type | Description | | ------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `revision` | String, 127 character maximum | **Required**. A unique ID for this deployment, visible in the [Summary](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/apm-overview-page) page and on the [Deployments](https://docs.newrelic.com/docs/apm/applications-menu/events/deployments-page) 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](https://docs.newrelic.com/docs/apm/applications-menu/events/deployments-page) page when you select **(selected deployment) > Change log**. | | `description` | String, 65535 character maximum | **Optional**. A high-level description of this deployment, visible in the [Summary](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/apm-overview-page) page and on the [Deployments](https://docs.newrelic.com/docs/apm/applications-menu/events/deployments-page) page when you select an individual deployment. | | `user` | String, 31 character maximum | **Optional**. A username to associate with the deployment, visible in the [Summary](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/apm-overview-page) page and on the [Deployments](https://docs.newrelic.com/docs/apm/applications-menu/events/deployments-page) page. | | `timestamp` | ISO 8601 | **Optional**. When the deployment occurred, down to the second. If not specified, the deployment will be recorded at the time when the API call was received. Timestamp requirements: - Must be in UTC time. - Must be after the most recent deployment timestamp. - Cannot be in the future. - Must be in ISO8601 format; for example, `"2019-10-08T00:15:36Z"`. | ## Record deployments using the New Relic agent [#agent] > #### ⚠️ IMPORTANT > > The REST API v2 methods referenced below [reach end of life on July 31, 2027](/eol/2026/07/eol-07-31-26-rest-api-v2). Record deployments with the NerdGraph `changeTrackingCreateEvent` mutation instead, see the [migration guide](https://docs.newrelic.com/docs/apis/rest-api-v2/migrate-to-nerdgraph/#deployments). Some agents have additional methods to record deployments: - **All agents**: Use the New Relic [REST API v2](#api-instructions). - **C**: No SDK-specific methods. Use the [REST API](#api-instructions). - **Go**: No agent-specific methods. Use the [REST API](#api-instructions). - **Java**: Call the [Java agent `jar`](https://docs.newrelic.com/docs/agents/java-agent/instrumentation/recording-deployments-java-agent). - **.NET**: Use [PowerShell and the REST API](#powershell). - **Node.js**: No agent-specific methods. Use the [REST API](#api-instructions). - **PHP**: Use a [PHP script](https://docs.newrelic.com/docs/agents/php-agent/features/recording-deployments-using-php-script). - **Python**: Use the [`record-deploy`](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/python-agent-admin-script#record-deploy) subcommand of the `newrelic-admin` script. - **Ruby**: Use a Capistrano recipe or the `newrelic deployments` command. More details [here](https://docs.newrelic.com/docs/agents/ruby-agent/features/recording-deployments-ruby-agent). ## View deployment details [#dep_procedures] After you configure the deployment information, you can view and drill down into details in the UI. For tips, see our change tracking document [How to view and analyze your changes in New Relic](https://docs.newrelic.com/docs/change-tracking/change-tracking-view-analyze). ## Notify your team about deployments [#webhooks] Whether you're tracking deployments with the REST API or the newer [GraphQL API](https://docs.newrelic.com/docs/change-tracking/change-tracking-introduction), you can notify your team members using a webhook. For details, see the change tracking [webhook instructions](https://docs.newrelic.com/docs/change-tracking/change-tracking-webhooks).