deployments.upsert

Create a deployment or patch an existing API-created deployment using a stable reference_id.

Use this method for idempotent ingestion when the caller may not know whether DX already has the deployment. Use deployments.update when a missing deployment should be an error instead of creating a new record.

Facts


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

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`reference_id`	`Text` or `Integer`	Stable unique identifier used to find the deployment. Example: `release-v2.4.0`

When reference_id does not already exist, service, deployed_at, and either a recognized repository or merge_commit_shas are also required. See deployments.create for attribution guidance.

Optional arguments

Omitted fields remain unchanged when patching an existing deployment.

Name	Type	Description
`deployed_at`	`Timestamp`	Deployment timestamp. DX accepts an ISO-8601 timestamp, Unix seconds, or Unix milliseconds.
`service`	`Object` or `Text`	Service receiving the deployment. Send an object with `identifier` and optional `name`, or a string to use the same value for both fields. Providing this field replaces the deployment’s service association.
`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. Example: `Argo CD`
`metadata`	`JSON`	Additional data you define. See Metadata replacement.
`integration_branch`	`Text`	Branch used to integrate changes before release. Example: `develop`
`success`	`Boolean`	Whether the deployment succeeded. Send a JSON boolean, not a string.

Patch behavior

An unknown reference_id creates a deployment and returns action: "created".
An existing reference_id patches that deployment and returns action: "updated".
Fields omitted from an update request retain their existing values.
Existing deployments created by a native connector or deployment inference rule cannot be changed through this endpoint.
Changes to attribution fields, including the repository, SHA, service, environment, integration branch, or deployment time, cause DX to recalculate deployment attribution asynchronously.

Metadata replacement

The metadata key uses replacement semantics:

Omit metadata to leave existing metadata unchanged.
Send an object to replace all existing metadata.
Send {} or null to remove all existing metadata.

Metadata is replaced as a complete value rather than merged recursively. Include every metadata field you want to retain in each request.

Recording regional deployment timestamps

You can use metadata to collect timestamps as a release reaches different production regions. Send the same deployment reference_id for each update and include all regions known so far:

curl -X POST https://yourinstance.getdx.net/api/deployments.upsert \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  --data '{
    "reference_id": "release-v2.4.0",
    "metadata": {
      "regions": {
        "us-east-1": { "deployed_at": "2026-09-29T16:00:00Z" },
        "eu-west-1": { "deployed_at": "2026-09-29T16:18:00Z" }
      }
    }
  }'

Regional metadata is available for custom reporting. The deployment remains one deployment record, and its top-level deployed_at value is used by standard DORA reporting.

Example requests

Create when missing

curl -X POST https://yourinstance.getdx.net/api/deployments.upsert \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  --data '{
    "reference_id": "release-v2.4.0",
    "deployed_at": "2026-09-29T16:00:00Z",
    "service": { "identifier": "payments-service", "name": "Payments" },
    "repository": "my-org/payments",
    "commit_sha": "d1a34f0"
  }'

Patch when present

curl -X POST https://yourinstance.getdx.net/api/deployments.upsert \
  -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",
    "success": true
  }'

Success response

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

action is created when the request creates the deployment and updated when it patches an existing deployment.

Errors

Error	Description
`not_authed`	The request did not include a valid API key.
`required_params_missing`	`reference_id` is missing, a supplied required value is blank, or create fields are missing.
`invalid_reference_id`	`reference_id` is not text or an integer.
`deployment_not_api_managed`	The existing 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.