deployments.update

Patch an existing API-created deployment.

Unlike deployments.upsert, this method never creates a deployment. It returns deployment_not_found when reference_id does not exist.

Facts


Method	`POST https://yourinstance.getdx.net/api/deployments.update`

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`reference_id`	`Text` or `Integer`	Unique identifier of an existing deployment. Example: `release-v2.4.0`

Optional arguments

Omitted fields remain unchanged.

Name	Type	Description
`deployed_at`	`Timestamp`	Deployment timestamp. DX accepts an ISO-8601 timestamp, Unix seconds, or Unix milliseconds.
`service`	`Object` or `Text`	Replacement service. Send an object with `identifier` and optional `name`, or a string to use the same value for both fields.
`repository`	`Text`	Repository name, including the organization or source-specific project prefix.
`commit_sha`	`Text`	Deployed commit SHA, between 7 and 40 characters. Providing this field clears stored `merge_commit_shas`.
`merge_commit_shas`	`Array<Text>`	Merge commit SHAs included in the deployment. Providing a non-empty array clears the stored `commit_sha`.
`environment`	`Text`	Deployment environment. Example: `production`
`source_url`	`Text`	External URL with more information about the deployment.
`source_name`	`Text`	Name of the deployment source.
`metadata`	`JSON`	Additional data you define. Omit this key to preserve existing metadata. An object replaces all metadata; `{}` or `null` clears it.
`integration_branch`	`Text`	Branch used to integrate changes before release.
`success`	`Boolean`	Whether the deployment succeeded. Send a JSON boolean, not a string.

Use deployments.update when the deployment must already exist and a missing or mistyped reference_id should return an error instead of creating a new record. Use deployments.upsert for idempotent ingestion that should create a deployment when none exists for the provided reference_id.

Only fields included in the request are changed. Changes that affect pull request attribution cause DX to remove the previous attribution and recalculate it asynchronously.

This method can update only deployments created through the Deployments API. Deployments managed by a native connector or deployment inference rule return deployment_not_api_managed.

Example request

curl -X POST https://yourinstance.getdx.net/api/deployments.update \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  --data '{
    "reference_id": "release-v2.4.0",
    "source_url": "https://deployments.example.com/releases/release-v2.4.0",
    "metadata": {
      "version": "v2",
      "region": "eu-west-1"
    }
  }'

Success response

{
  "ok": true,
  "action": "updated",
  "reference_id": "release-v2.4.0"
}

Errors

Error	Description
`not_authed`	The request did not include a valid API key.
`required_params_missing`	`reference_id` is missing or a supplied required value is blank.
`invalid_reference_id`	`reference_id` is not text or an integer.
`deployment_not_found`	No deployment exists for `reference_id`. This response uses HTTP status 404.
`deployment_not_api_managed`	The deployment is managed by a connector or inference rule.
`invalid_service_param`	`service` is not a string or an object with an `identifier`.
`invalid_timestamp`	`deployed_at` is not a readable timestamp.
`commit_sha_invalid`	`commit_sha` is invalid.
`merge_commit_shas_invalid`	`merge_commit_shas` is not a valid array of SHA strings.
`ambiguous_commit_sha_arguments`	Both `commit_sha` and a non-empty `merge_commit_shas` value were supplied.
`repository_not_found`	The repository could not be found.
`integration_branch_not_valid`	The integration branch could not be validated for the repository.
`metadata_invalid`	Metadata could not be processed.