---
title: "Submit deployment data"
method: POST
path: "/rest/deployments/0.1/bulk"
tags: ["Deployments"]
---

# Submit deployment data

`POST /rest/deployments/0.1/bulk`

Update / insert deployment data.

Deployments are identified by the combination of `pipelineId`, `environmentId` and `deploymentSequenceNumber`, and existing deployment data for the same deployment will be replaced if it exists and the `updateSequenceNumber` of existing data is less than the incoming data.

Submissions are processed asynchronously. Submitted data will eventually be available in Jira. Most updates are available within a short period of time, but may take some time during peak load and/or maintenance times. The `getDeploymentByKey` operation can be used to confirm that data has been stored successfully (if needed).

In the case of multiple deployments being submitted in one request, each is validated individually prior to submission. Details of which deployments failed submission (if any) are available in the response object.

## Request body

- object — The payload used to submit (update / insert) deployment data.
  - `properties` object — Properties assigned to deployment data that can then be used for delete / query operations. Examples might be an account or user ID that can then be used to clean up data if an account is removed from the Provider system. Properties are supplied as key/value pairs, and a maximum of 5 properties can be supplied, keys cannot contain ':' or start with '_'.
  - `deployments` object[], required — A list of deployments to submit to Jira. Each deployment may be associated with one or more Jira issue keys, and will be associated with any properties included in this request.
    - `deploymentSequenceNumber` integer, required — This is the identifier for the deployment. It must be unique for the specified pipeline and environment. It must be a monotonically increasing number, as this is used to sequence the deployments.
    - `updateSequenceNumber` integer, required — A number used to apply an order to the updates to the deployment, as identified by the deploymentSequenceNumber, in the case of out-of-order receipt of update requests. It must be a monotonically increasing number. For example, epoch time could be one way to generate the updateSequenceNumber.
    - `issueKeys` string[] — Deprecated. The Jira issue keys to associate the Deployment information with. Should replace this field with the "associations" field to associate Deployment information with issueKeys or other types of associations.
    - `associations` union[] — The entities to associate the Deployment information with.
      - union
        - IssueIdOrKeysAssociation — An association type referencing issues in Jira.
          - `associationType` 'issueKeys' | 'issueIdOrKeys', required — Defines the association type.
          - `values` string[], required — The Jira issue keys or IDs to associate the entity with. The number of values counted across all associationTypes must not exceed a limit of 500.
        - ServiceIdOrKeysAssociation — An association type referencing service ID or keys.
          - `associationType` 'serviceIdOrKeys', required — Defines the association type.
          - `values` string[], required — The service ID or keys to associate the entity with. The number of values counted across all associationTypes must not exceed a limit of 500.
        - EntityAssociation — An association type referencing another entity
          - `associationType` 'commit' | 'repository', required — Defines the association type. Currently supported entities can be found in this field's value enums list.
          - `values` union[], required — The entity keys that represent the entities to be associated. The number of values counted across all associationTypes must not exceed a limit of 500.
            - union
              - …
    - `displayName` string, required — The human-readable name for the deployment. Will be shown in the UI.
    - `url` string, uri, required — A URL users can use to link to this deployment, in this environment.
    - `description` string, required — A short description of the deployment
    - `lastUpdated` string, date-time, required — The last-updated timestamp to present to the user as a summary of the state of the deployment.
    - `label` string — An (optional) additional label that may be displayed with deployment information. Can be used to display version information etc. for the deployment.
    - `duration` integer — The duration of the deployment (in seconds).
    - `state` 'unknown' | 'pending' | 'in_progress' | 'cancelled' | 'failed' | 'rolled_back' | 'successful', required — The state of the deployment
    - `pipeline` object, required — This object models the Continuous Delivery (CD) Pipeline concept, an automated process (usually comprised of multiple stages) for getting software from version control right through to the production environment.
      - `id` string, required — The identifier of this pipeline, must be unique for the provider.
      - `displayName` string, required — The name of the pipeline to present to the user.
      - `url` string, uri, required — A URL users can use to link to this deployment pipeline.
    - `environment` object, required — The environment that the deployment is present in.
      - `id` string, required — The identifier of this environment, must be unique for the provider so that it can be shared across pipelines.
      - `displayName` string, required — The name of the environment to present to the user.
      - `type` 'unmapped' | 'development' | 'testing' | 'staging' | 'production', required — The type of the environment.
    - `commands` object[] — A list of commands to be actioned for this Deployment
      - `command` string — The command name.
    - `schemaVersion` '1.0' — The DeploymentData schema version used for this deployment data. Placeholder to support potential schema changes in the future.
  - `providerMetadata` object — Information about the provider. This is useful for auditing, logging, debugging, and other internal uses. It is not considered private information. Hence, it may not contain personally identifiable information.
    - `product` string — An optional name of the source of the deployments data.

## Response `202`

Submission accepted. Each submitted deployment that is of a valid format will eventually be available in Jira.

Details of which deployments were submitted and which failed submission (due to data format problems etc.) are available in the response object.

- object — The result of a successful submitDeployments request.
  - `acceptedDeployments` object[] — The keys of deployments that have been accepted for submission. A deployment key is a composite key that consists of `pipelineId`, `environmentId` and `deploymentSequenceNumber`. A deployment may be rejected if it was only associated with unknown issue keys. Note that a deployment that isn't updated due to it's updateSequenceNumber being out of order is not considered a failed submission.
    - `pipelineId` string, required — The identifier of a pipeline, must be unique for the provider.
    - `environmentId` string, required — The identifier of an environment, must be unique for the provider so that it can be shared across pipelines.
    - `deploymentSequenceNumber` integer, required — This is the identifier for the deployment. It must be unique for the specified pipeline and environment. It must be a monotonically increasing number, as this is used to sequence the deployments.
  - `rejectedDeployments` object[] — Details of deployments that have not been accepted for submission, usually due to a problem with the request data. The object will contain the deployment key and any errors associated with that deployment that have prevented it being submitted.
    - `key` object, required — Fields that uniquely reference a deployment.
      - `pipelineId` string, required — The identifier of a pipeline, must be unique for the provider.
      - `environmentId` string, required — The identifier of an environment, must be unique for the provider so that it can be shared across pipelines.
      - `deploymentSequenceNumber` integer, required — This is the identifier for the deployment. It must be unique for the specified pipeline and environment. It must be a monotonically increasing number, as this is used to sequence the deployments.
    - `errors` object[], required — The error messages for the rejected deployment
      - `message` string, required — A human-readable message describing the error.
      - `errorTraceId` string — An optional trace ID that can be used by Jira developers to locate the source of the error.
  - `unknownIssueKeys` string[] — Issue keys that are not known on this Jira instance (if any). These may be invalid keys (e.g. `UTF-8` is sometimes incorrectly identified as a Jira issue key), or they may be for projects that no longer exist. If a deployment has been associated with issue keys other than those in this array it will still be stored against those valid keys. If a deployment was only associated with issue keys deemed to be invalid it won't be persisted.
  - `unknownAssociations` union[] — Associations (e.g. Issue Keys or Service IDs) that are not known on this Jira instance (if any). These may be invalid keys (e.g. `UTF-8` is sometimes incorrectly identified as a Jira issue key), or they may be for projects that no longer exist. If a deployment has been associated with any other association other than those in this array it will still be stored against those valid associations. If a deployment was only associated with the associations in this array, it is deemed to be invalid and it won't be persisted.
    - union
      - IssueIdOrKeysAssociation — An association type referencing issues in Jira.
        - `associationType` 'issueKeys' | 'issueIdOrKeys', required — Defines the association type.
        - `values` string[], required — The Jira issue keys or IDs to associate the entity with. The number of values counted across all associationTypes must not exceed a limit of 500.
      - ServiceIdOrKeysAssociation — An association type referencing service ID or keys.
        - `associationType` 'serviceIdOrKeys', required — Defines the association type.
        - `values` string[], required — The service ID or keys to associate the entity with. The number of values counted across all associationTypes must not exceed a limit of 500.
      - EntityAssociation — An association type referencing another entity
        - `associationType` 'commit' | 'repository', required — Defines the association type. Currently supported entities can be found in this field's value enums list.
        - `values` union[], required — The entity keys that represent the entities to be associated. The number of values counted across all associationTypes must not exceed a limit of 500.
          - union
            - object — Identifies an individual commit in a repository.
              - …
            - object — Identifies an individual repository.
              - …

## Other responses

- `400` — Request has incorrect format. Note that in the case of an individual deployment having an invalid format (rather than the request as a whole) the response for the request will be a 202 and details of the invalid deployment will be contained in the response object.
- `401` — Missing a JWT token, or token is invalid.
- `403` — The JWT token used does not correspond to an app that defines the `jiraDeploymentInfoProvider` module, or the app does not define the 'WRITE' scope.
- `413` — Data is too large. Submit fewer deployments in each payload.
- `429` — API rate limit has been exceeded.
- `503` — Service is unavailable due to maintenance or other reasons.
- `default` — An unknown error has occurred.

---

[API](https://skmtc.net/atlassian/apis/jira-software-cloud-api.md) · [All operations](https://skmtc.net/atlassian/apis/jira-software-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/jira-software-cloud-api/revisions/4e108d54b990/schema)