---
title: "Submit build data"
method: POST
path: "/rest/builds/0.1/bulk"
tags: ["Builds"]
---

# Submit build data

`POST /rest/builds/0.1/bulk`

Update / insert builds data.

Builds are identified by the combination of `pipelineId` and `buildNumber`, and existing build data for the same
build will be replaced if it exists and the `updateSequenceNumber` of the existing data is less than the
incoming data.

Submissions are performed 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 `getBuildByKey` operation can be used to confirm that data has been stored successfully (if needed).

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

## Request body

- object — The payload used to submit (update / insert) build data.
  - `properties` object — Properties assigned to build 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. Note that these properties will never be returned with build data. They are not intended for use as metadata to associate with a build. Internally they are stored as a hash so that personal information etc. is never stored within Jira. Properties are supplied as key/value pairs, a maximum of 5 properties can be supplied, and keys must not contain ':' or start with '_'.
  - `builds` object[], required — A list of builds to submit to Jira. Each build may be associated with one or more Jira issue keys, and will be associated with any properties included in this request.
    - `schemaVersion` '1.0' — The schema version used for this data. Placeholder to support potential schema changes in the future.
    - `pipelineId` string, required — An ID that relates a sequence of builds. Depending on your use case this might be a project ID, pipeline ID, plan key etc. - whatever logical unit you use to group a sequence of builds. The combination of `pipelineId` and `buildNumber` must uniquely identify a build you have provided.
    - `buildNumber` integer, required — Identifies a build within the sequence of builds identified by the build `pipelineId`. Used to identify the 'most recent' build in that sequence of builds. The combination of `pipelineId` and `buildNumber` must uniquely identify a build you have provided.
    - `updateSequenceNumber` integer, required — A number used to apply an order to the updates to the build, as identified by `pipelineId` and `buildNumber`, 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`. Updates for a build that is received with an `updateSqeuenceNumber` less than or equal to what is currently stored will be ignored.
    - `displayName` string, required — The human-readable name for the build. Will be shown in the UI.
    - `description` string — An optional description to attach to this build. This may be anything that makes sense in your system.
    - `label` string — A human-readable string that to provide information about the build.
    - `url` string, URL, required — The URL to this build in your system.
    - `state` 'pending' | 'in_progress' | 'successful' | 'failed' | 'cancelled' | 'unknown', required — The state of a build. * `pending` - The build is queued, or some manual action is required. * `in_progress` - The build is currently running. * `successful` - The build completed successfully. * `failed` - The build failed. * `cancelled` - The build has been cancelled or stopped. * `unknown` - The build is in an unknown state.
    - `lastUpdated` string, date-time, required — The last-updated timestamp to present to the user as a summary of the state of the build.
    - `issueKeys` string[] — The Jira issue keys to associate the build information with. You are free to associate issue keys in any way you like. However, we recommend that you use the name of the branch the build was executed on, and extract issue keys from that name using a simple regex. This has the advantage that it provides an intuitive association of builds to issue keys.
    - `associations` IssueIdOrKeysAssociation[] — The Jira issue keys or IDs to associate the build with.
      - `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.
    - `testInfo` object — Information about tests that were executed during a build.
      - `totalNumber` integer, required — The total number of tests considered during a build.
      - `numberPassed` integer, required — The number of tests that passed during a build.
      - `numberFailed` integer, required — The number of tests that failed during a build.
      - `numberSkipped` integer — The number of tests that were skipped during a build.
    - `references` object[] — Optional information that links a build to a commit, branch etc.
      - `commit` object — Details about the commit the build was run against.
        - `id` string, required — The ID of the commit. E.g. for a Git repository this would be the SHA1 hash.
        - `repositoryUri` string, required — An identifier for the repository containing the commit. In most cases this should be the URL of the repository in the SCM provider. For cases where the build was executed against a local repository etc. this should be some identifier that is unique to that repository.
      - `ref` object — Details about the ref the build was run on.
        - `name` string, required — The name of the ref the build ran on
        - `uri` string, required — An identifer for the ref. In most cases this should be the URL of the tag/branch etc. in the SCM provider. For cases where the build was executed against a local repository etc. this should be something that uniquely identifies the ref.
  - `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 builds data.

## Response `202`

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

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

- object — The result of a successful `submitBuilds` request.
  - `acceptedBuilds` object[] — The keys of builds that have been accepted for submission. A build key is a composite key that consists of `pipelineId` and `buildNumber`. A build may be rejected if it was only associated with unknown issue keys, or if the submitted data for that build does not match the required schema. Note that a build that isn't updated due to it's `updateSequenceNumber` being out of order is not considered a failed submission.
    - `pipelineId` string, required — An ID that relates a sequence of builds. Depending on your system this might be a project ID, pipeline ID, plan key etc. - whatever logical unit you use to group a sequence of builds. The combination of `pipelineId` and `buildNumber` must uniquely identify the build.
    - `buildNumber` integer, required — Identifies a build within the sequence of builds identified by the build `pipelineId`. Used to identify the 'most recent' build in that sequence of builds. The combination of `pipelineId` and `buildNumber` must uniquely identify the build.
  - `rejectedBuilds` object[] — Details of builds that have not been accepted for submission. A build may be rejected if it was only associated with unknown issue keys, or if the submitted data for the build does not match the required schema.
    - `key` object, required — Fields that uniquely reference a build.
      - `pipelineId` string, required — An ID that relates a sequence of builds. Depending on your system this might be a project ID, pipeline ID, plan key etc. - whatever logical unit you use to group a sequence of builds. The combination of `pipelineId` and `buildNumber` must uniquely identify the build.
      - `buildNumber` integer, required — Identifies a build within the sequence of builds identified by the build `pipelineId`. Used to identify the 'most recent' build in that sequence of builds. The combination of `pipelineId` and `buildNumber` must uniquely identify the build.
    - `errors` object[], required — The error messages for the rejected build
      - `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 build has been associated with issue keys other than those in this array it will still be stored against those valid keys. If a build was only associated with issue keys deemed to be invalid it won't be persisted.
  - `unknownAssociations` IssueIdOrKeysAssociation[] — Associations 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 build has been associated with any other association other than those in this array it will still be stored against those valid associations. If a build was only associated with the associations in this array, it is deemed to be invalid and it won't be persisted.
    - `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.

## Other responses

- `400` — Request has incorrect format. Note that in the case of an individual build 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 build 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 `jiraBuildInfoProvider` module, or the app does not define the 'WRITE' scope.
- `413` — Data is too large. Submit fewer builds 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)