openapi: 3.2.0 info: contact: url: https://getsupport.atlassian.com description: Jira Software Cloud REST API documentation license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html termsOfService: http://atlassian.com/terms/ title: Jira Software Cloud Development Information API version: 1001.0.0 servers: - url: https://your-domain.atlassian.net tags: - name: Development Information description: APIs related to integrating development information (commits, branches and pull requests) with Jira. paths: /rest/devinfo/0.10/bulk: post: tags: - Development Information summary: Store development information description: Stores development information provided in the request to make it available when viewing issues in Jira. Existing repository and entity data for the same ID will be replaced if the updateSequenceId of 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. operationId: storeDevelopmentInformation parameters: - name: Authorization in: header description: All requests must be signed with either a Connect JWT token or OAuth token for an on-premise integration that corresponds to an app installed in Jira. If the JWT token corresponds to a Connect app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details about Connect JWT tokens. See https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/ for details about on-premise integrations. required: true schema: type: string requestBody: content: application/json: schema: title: DevInformation type: object required: - repositories properties: repositories: type: array maxItems: 100 description: List of repositories containing development information. Must not contain duplicates. Maximum number of entities across all repositories is 1000. items: title: Repository type: object required: - id - name - updateSequenceId - url properties: name: type: string example: atlassian-connect-jira-example description: The name of this repository. Max length is 255 characters. maxLength: 255 description: type: string example: The repository which stores code of the Atlassian Connect Add-on Devinfo application. description: Description of this repository. Max length is 1024 characters. maxLength: 1024 forkOf: type: string example: 56c7c750-cee2-48e2-b920-d7706dfd11f7 description: The ID of the repository this repository was forked from, if it's a fork. Max length is 1024 characters. maxLength: 1024 url: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example description: The URL of this repository. Max length is 2000 characters. maxLength: 2000 format: url commits: type: array description: List of commits to update in this repository. Must not contain duplicate entity IDs. Maximum number of commits is 400 items: title: Commit type: object required: - id - updateSequenceId - author - authorTimestamp - displayId - fileCount - message - url properties: id: type: string example: a7727ee6350c33cdf90826dc21abaa26a5704370 description: The identifier or hash of the commit. Will be used for cross entity linking. Must be unique for all commits within a repository, i.e., only one commit can have ID 'X' in repository 'Y'. But adding, e.g., a branch with ID 'X' to repository 'Y' is acceptable. Only alphanumeric characters, and '~.-_', are allowed. Max length is 1024 characters issueKeys: type: array example: '["ISSUE-1","TEST-2"]' description: List of issues keys that this entity is associated with. They must be valid Jira issue keys. minItems: 1 maxItems: 500 pattern: ^\p{L}[\p{L}\p{Digit}_]{1,255}-\p{Digit}{1,255}$ items: type: string deprecated: true associations: description: The Jira issue keys or IDs to associate the commit with. type: array items: $ref: '#/components/schemas/IssueIdOrKeysAssociation' updateSequenceId: type: integer format: int64 example: 1523494301248 description: An ID used to apply an ordering to updates for this entity in the case of out-of-order receipt of update requests. This can be any monotonically increasing number. A suggested implementation is to use epoch millis from the provider system, but other alternatives are valid (e.g. a provider could store a counter against each entity and increment that on each update to Jira). Updates for an entity that are received with an updateSqeuenceId lower than what is currently stored will be ignored. hash: type: string description: Deprecated. Use the id field instead. maxLength: 255 flags: type: array example: '[MERGE_COMMIT]' description: The set of flags for this commit uniqueItems: true items: type: string enum: - MERGE_COMMIT message: type: string example: README.md edited online with Bitbucket description: The commit message. Max length is 1024 characters. If anything longer is supplied, it will be truncated down to 1024 characters. maxLength: 1024 author: title: Author type: object properties: name: type: string example: Jane Doe description: Deprecated. The name of this user in a format suitable for display. Max length is 255 characters. maxLength: 255 email: type: string example: jane_doe@atlassian.com description: The email address of the user. Used to associate the user with a Jira user. Max length is 255 characters. maxLength: 255 username: type: string example: jdoe description: Deprecated. The username of the user. Used to associate the user with a Jira user if there are multiple users for a given email. Max length is 255 characters. maxLength: 255 url: type: string example: https://atlassian.com/account/jane_doe description: Deprecated. The URL of the profile for this user. Max length is 2000 characters. maxLength: 2000 avatar: type: string example: https://atlassian.com/account/jane_doe/avatar/32 description: Deprecated. The URL of the avatar for this user. Max length is 2000 characters. maxLength: 2000 description: Describes the author of a particular entity fileCount: type: integer format: int32 example: 1 description: The total number of files added, removed, or modified by this commit minimum: 0 url: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/commits/a7727ee6350c33cdf90826dc21abaa26a5704370 description: The URL of this commit. Max length is 2000 characters. maxLength: 2000 format: url files: type: array description: List of file changes. Max number of files is 10. Currently, only the first 5 files are shown (sorted by path) in the UI. This UI behavior may change without notice. maxItems: 10 items: title: File type: object required: - changeType - linesAdded - linesRemoved - path - url properties: path: type: string example: /home/user/src/atlassian-connect-jira-example/README.md description: The path of the file. Max length is 1024 characters. maxLength: 1024 url: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/src/a7727ee6350c33cdf90826dc21abaa26a5704370/README.md description: The URL of this file. Max length is 2000 characters. maxLength: 2000 format: url changeType: type: string example: MODIFIED description: The operation performed on this file enum: - ADDED - COPIED - DELETED - MODIFIED - MOVED - UNKNOWN linesAdded: type: integer format: int32 example: 0 description: Number of lines added to the file minimum: 0 linesRemoved: type: integer format: int32 example: 1 description: Number of lines removed from the file minimum: 0 description: Describes changes to a file authorTimestamp: type: string example: '2016-10-31T23:27:25+00:00' description: The author timestamp of this commit. Formatted as a UTC ISO 8601 date time format. displayId: type: string example: a7727ee description: Shortened identifier for this commit, used for display. Max length is 255 characters. maxLength: 255 description: Represents a commit in the version control system. minItems: 0 maxItems: 400 branches: type: array description: List of branches to update in this repository. Must not contain duplicate entity IDs. Maximum number of branches is 400. items: title: Branch type: object required: - id - updateSequenceId - lastCommit - name - url properties: id: type: string example: c6c7c750-cee2-48e2-b920-d7706dfd11f9 description: The ID of this entity. Will be used for cross entity linking. Must be unique by entity type within a repository, i.e., only one commit can have ID 'X' in repository 'Y'. But adding, e.g., a branch with ID 'X' to repository 'Y' is acceptable. Only alphanumeric characters, and '~.-_', are allowed. Max length is 1024 characters. maxLength: 1024 issueKeys: type: array example: '["ISSUE-1","TEST-2"]' description: List of issues keys that this entity is associated with. They must be valid Jira issue keys. minItems: 1 maxItems: 500 pattern: ^\p{L}[\p{L}\p{Digit}_]{1,255}-\p{Digit}{1,255}$ items: type: string deprecated: true associations: description: The Jira issue keys or IDs to associate the branch with. type: array items: $ref: '#/components/schemas/IssueIdOrKeysAssociation' updateSequenceId: type: integer format: int64 example: 1523494301248 description: An ID used to apply an ordering to updates for this entity in the case of out-of-order receipt of update requests. This can be any monotonically increasing number. A suggested implementation is to use epoch millis from the provider system, but other alternatives are valid (e.g. a provider could store a counter against each entity and increment that on each update to Jira). Updates for an entity that are received with an updateSqeuenceId lower than what is currently stored will be ignored. name: type: string example: master description: The name of the branch. Max length is 512 characters. maxLength: 512 lastCommit: title: Commit type: object required: - id - issueKeys - updateSequenceId - author - authorTimestamp - displayId - fileCount - message - url properties: id: type: string example: a7727ee6350c33cdf90826dc21abaa26a5704370 description: The identifier or hash of the commit. Will be used for cross entity linking. Must be unique for all commits within a repository, i.e., only one commit can have ID 'X' in repository 'Y'. But adding, e.g., a branch with ID 'X' to repository 'Y' is acceptable. Only alphanumeric characters, and '~.-_', are allowed. Max length is 1024 characters issueKeys: type: array example: '["ISSUE-1","TEST-2"]' description: List of issues keys that this entity is associated with. They must be valid Jira issue keys. minItems: 1 maxItems: 500 pattern: ^\p{L}[\p{L}\p{Digit}_]{1,255}-\p{Digit}{1,255}$ items: type: string updateSequenceId: type: integer format: int64 example: 1523494301248 description: An ID used to apply an ordering to updates for this entity in the case of out-of-order receipt of update requests. This can be any monotonically increasing number. A suggested implementation is to use epoch millis from the provider system, but other alternatives are valid (e.g. a provider could store a counter against each entity and increment that on each update to Jira). Updates for an entity that are received with an updateSqeuenceId lower than what is currently stored will be ignored. hash: type: string description: Deprecated. Use the id field instead. maxLength: 255 flags: type: array example: '[MERGE_COMMIT]' description: The set of flags for this commit uniqueItems: true items: type: string enum: - MERGE_COMMIT message: type: string example: README.md edited online with Bitbucket description: The commit message. Max length is 1024 characters. If anything longer is supplied, it will be truncated down to 1024 characters. maxLength: 1024 author: title: Author type: object properties: name: type: string example: Jane Doe description: Deprecated. The name of this user in a format suitable for display. Max length is 255 characters. maxLength: 255 email: type: string example: jane_doe@atlassian.com description: The email address of the user. Used to associate the user with a Jira user. Max length is 255 characters. maxLength: 255 username: type: string example: jdoe description: Deprecated. The username of the user. Used to associate the user with a Jira user if there are multiple users for a given email. Max length is 255 characters. maxLength: 255 url: type: string example: https://atlassian.com/account/jane_doe description: Deprecated. The URL of the profile for this user. Max length is 2000 characters. maxLength: 2000 avatar: type: string example: https://atlassian.com/account/jane_doe/avatar/32 description: Deprecated. The URL of the avatar for this user. Max length is 2000 characters. maxLength: 2000 description: Describes the author of a particular entity fileCount: type: integer format: int32 example: 1 description: The total number of files added, removed, or modified by this commit minimum: 0 url: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/commits/a7727ee6350c33cdf90826dc21abaa26a5704370 description: The URL of this commit. Max length is 2000 characters. maxLength: 2000 format: url files: type: array description: List of file changes. Max number of files is 10. Currently, only the first 5 files are shown (sorted by path) in the UI. This UI behavior may change without notice. maxItems: 10 items: title: File type: object required: - changeType - linesAdded - linesRemoved - path - url properties: path: type: string example: /home/user/src/atlassian-connect-jira-example/README.md description: The path of the file. Max length is 1024 characters. maxLength: 1024 url: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/src/a7727ee6350c33cdf90826dc21abaa26a5704370/README.md description: The URL of this file. Max length is 2000 characters. maxLength: 2000 format: url changeType: type: string example: MODIFIED description: The operation performed on this file enum: - ADDED - COPIED - DELETED - MODIFIED - MOVED - UNKNOWN linesAdded: type: integer format: int32 example: 0 description: Number of lines added to the file minimum: 0 linesRemoved: type: integer format: int32 example: 1 description: Number of lines removed from the file minimum: 0 description: Describes changes to a file authorTimestamp: type: string example: '2016-10-31T23:27:25+00:00' description: The author timestamp of this commit. Formatted as a UTC ISO 8601 date time format. displayId: type: string example: a7727ee description: Shortened identifier for this commit, used for display. Max length is 255 characters. maxLength: 255 description: Represents a commit in the version control system. createPullRequestUrl: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/pull-requests/new description: The URL of the page for creating a pull request from this branch. Max length is 2000 characters. maxLength: 2000 url: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/branch/master description: The URL of the branch. Max length is 2000 characters. maxLength: 2000 description: Represents a branch in the version control system minItems: 0 maxItems: 400 pullRequests: type: array description: List of pull requests to update in this repository. Must not contain duplicate entity IDs. Maximum number of pull requests is 400 items: title: PullRequest type: object required: - id - updateSequenceId - author - commentCount - displayId - lastUpdate - sourceBranch - status - title - url properties: id: type: string example: c6c7c750-cee2-48e2-b920-d7706dfd11f9 description: The ID of this entity. Will be used for cross entity linking. Must be unique by entity type within a repository, i.e., only one commit can have ID 'X' in repository 'Y'. But adding, e.g., a branch with ID 'X' to repository 'Y' is acceptable. Only alphanumeric characters, and '~.-_', are allowed. Max length is 1024 characters issueKeys: type: array example: '["ISSUE-1","TEST-2"]' description: List of issues keys that this entity is associated with. They must be valid Jira issue keys. minItems: 1 maxItems: 500 pattern: ^\p{L}[\p{L}\p{Digit}_]{1,255}-\p{Digit}{1,255}$ items: type: string deprecated: true associations: description: The Jira issue keys or IDs to associate the pull request with. type: array items: $ref: '#/components/schemas/IssueIdOrKeysAssociation' updateSequenceId: type: integer format: int64 example: 1523494301248 description: An ID used to apply an ordering to updates for this entity in the case of out-of-order receipt of update requests. This can be any monotonically increasing number. A suggested implementation is to use epoch millis from the provider system, but other alternatives are valid (e.g. a provider could store a counter against each entity and increment that on each update to Jira). Updates for an entity that are received with an updateSqeuenceId lower than what is currently stored will be ignored. status: type: string example: OPEN description: The status of the pull request. In the case of concurrent updates, priority is given in the order OPEN, MERGED, DECLINED, UNKNOWN enum: - OPEN - MERGED - DECLINED - UNKNOWN title: type: string example: 'Pull request 2, fixing all the issues caused by pull request #1' description: Title of the pull request. Max length is 1024 characters. maxLength: 1024 author: title: Author type: object properties: name: type: string example: Jane Doe description: Deprecated. The name of this user in a format suitable for display. Max length is 255 characters. maxLength: 255 email: type: string example: jane_doe@atlassian.com description: The email address of the user. Used to associate the user with a Jira user. Max length is 255 characters. maxLength: 255 username: type: string example: jdoe description: Deprecated. The username of the user. Used to associate the user with a Jira user if there are multiple users for a given email. Max length is 255 characters. maxLength: 255 url: type: string example: https://atlassian.com/account/jane_doe description: Deprecated. The URL of the profile for this user. Max length is 2000 characters. maxLength: 2000 avatar: type: string example: https://atlassian.com/account/jane_doe/avatar/32 description: Deprecated. The URL of the avatar for this user. Max length is 2000 characters. maxLength: 2000 description: Describes the author of a particular entity commentCount: type: integer format: int32 example: 42 description: The number of comments on the pull request sourceBranch: type: string example: ISSUE-1-feature-branch description: The name of the source branch of this PR. Max length is 255 characters. maxLength: 255 sourceBranchUrl: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/branch/ISSUE-1-feature-branch description: The url of the source branch of this PR. This is used to match this PR against the branch. Max length is 2000 characters. maxLength: 2000 format: url lastUpdate: type: string example: '2016-10-31T23:27:25+00:00' description: The most recent update to this PR. Formatted as a UTC ISO 8601 date time format. destinationBranch: type: string example: master description: The name of destination branch of this PR. Max length is 255 characters. maxLength: 255 destinationBranchUrl: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/src/master description: The url of the destination branch of this PR. Max length is 2000 characters. maxLength: 2000 format: url reviewers: type: array description: The list of reviewers of this pull request items: title: Reviewer type: object properties: name: type: string example: Jane Doe description: Deprecated. The name of this reviewer. Max length is 255 characters. maxLength: 255 approvalStatus: type: string example: APPROVED description: The approval status of this reviewer, default is UNAPPROVED. enum: - APPROVED - UNAPPROVED url: type: string example: https://atlassian.com/account/jane_doe description: Deprecated. The URL of the profile for this reviewer. Max length is 2000 characters. maxLength: 2000 format: url avatar: type: string example: https://atlassian.com/account/jane_doe/avatar/32 description: Deprecated. The URL of the avatar for this reviewer. Max length is 2000 characters. maxLength: 2000 format: url email: type: string example: jane_doe@example.com description: The email address of this reviewer. Max length is 254 characters. maxLength: 254 accountId: type: string example: 655363:e4ca5e2d-a901-40e3-877e-bf5d22c0f130 description: The Atlassian Account ID (AAID) of this reviewer. Max length is 128 characters. maxLength: 128 description: The reviewer of a pull request url: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/pull-requests/2 description: The URL of this pull request. Max length is 2000 characters. maxLength: 2000 format: url displayId: type: string example: Pull request 2 description: Shortened identifier for this pull request, used for display. Max length is 255 characters. maxLength: 255 description: Represents a pull request minItems: 0 maxItems: 400 avatar: type: string example: http://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/avatar/32 description: The URL of the avatar for this repository. Max length is 2000 characters. maxLength: 2000 format: url avatarDescription: type: string example: Avatar description description: Description of the avatar for this repository. Max length is 1024 characters. maxLength: 1024 id: type: string example: c6c7c750-cee2-48e2-b920-d7706dfd11f9 description: The ID of this entity. Will be used for cross entity linking. Must be unique by entity type within a repository, i.e., only one commit can have ID 'X' in repository 'Y'. But adding, e.g., a branch with ID 'X' to repository 'Y' is acceptable. Only alphanumeric characters, and '~.-_', are allowed. Max length is 1024 characters. maxLength: 1024 updateSequenceId: type: integer format: int64 example: 1523494301248 description: ' An ID used to apply an ordering to updates for this entity in the case of out-of-order receipt of update requests. This can be any monotonically increasing number. A suggested implementation is to use epoch millis from the provider system, but other alternatives are valid (e.g. a provider could store a counter against each entity and increment that on each update to Jira). Updates for an entity that are received with an updateSqeuenceId lower than what is currently stored will be ignored.' description: Represents a repository, containing development information such as commits, pull requests, and branches. preventTransitions: type: boolean description: Flag to prevent automatic issue transitions and smart commits being fired, default is false. operationType: type: string example: NORMAL description: Indicates the operation being performed by the provider system when sending this data. "NORMAL" - Data received during normal operation (e.g. a user pushing a branch). "BACKFILL" - Data received while backfilling existing data (e.g. indexing a newly connected account). Default is "NORMAL". Please note that "BACKFILL" operations have a much higher rate-limiting threshold but are also processed slower in comparison to "NORMAL" operations. enum: - NORMAL - BACKFILL properties: type: object description: 'Arbitrary properties to tag the submitted repositories with. These properties can be used for delete operations to e.g. clean up all development information associated with an account in the event that the account is removed from the provider system. Note that these properties will never be returned with repository or entity data. They are not intended for use as metadata to associate with a repository. Maximum length of each key or value is 255 characters. Maximum allowed number of properties key/value pairs is 5. Properties keys cannot start with ''_'' character. Properties keys cannot contain '':'' character. ' additionalProperties: type: string providerMetadata: title: ProviderMetadata description: 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. type: object properties: product: type: string description: An optional name of the source of the development information data. example: Bitbucket Server 6.7.2 description: Request object for development information push operations, entities are grouped by repository description: Request object, which contains development information required: true responses: '202': description: Submission accepted. Each submitted repository and entity that is of a valid format will be eventually available in Jira. content: application/json: schema: title: StoreDevinfoResult type: object properties: acceptedDevinfoEntities: type: object description: The IDs of devinfo entities that have been accepted for submission grouped by their repository IDs. Note that a devinfo entity that isn't updated due to it's updateSequenceId being out of order is not considered a failed submission. additionalProperties: title: EntityIds type: object properties: commits: type: array description: Commits IDs items: type: string branches: type: array description: Branch IDs items: type: string pullRequests: type: array description: Pull request IDs items: type: string description: IDs of entities grouped by entity type failedDevinfoEntities: type: object description: 'IDs of devinfo entities that have not been accepted for submission and caused error descriptions, usually due to a problem with the request data. The entities (if present) will be grouped by their repository id and type. Entity IDs are listed with errors associated with that devinfo entity that have prevented it being submitted. ' additionalProperties: title: RepositoryErrors type: object properties: errorMessages: type: array description: Repository errors items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. commits: type: array description: Commits errors items: title: EntityError type: object required: - id properties: id: type: string description: Entity id errorMessages: type: array description: Error message items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. description: Represents an error that happened with particular entity. branches: type: array description: Branches errors items: title: EntityError type: object required: - id properties: id: type: string description: Entity id errorMessages: type: array description: Error message items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. description: Represents an error that happened with particular entity. pullRequests: type: array description: Pull requests errors items: title: EntityError type: object required: - id properties: id: type: string description: Entity id errorMessages: type: array description: Error message items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. description: Represents an error that happened with particular entity. description: Represents errors related to a particular repository and its entities unknownIssueKeys: type: array description: '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 devinfo entity has been associated with issue keys other than those in this array it will still be stored against those valid keys. ' items: type: string unknownAssociations: description: '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 development information entity has been associated with any other association other than those in this array it will still be stored against those valid associations. If a development information entity was only associated with the associations in this array, it is deemed to be invalid and it won''t be persisted. ' type: array items: $ref: '#/components/schemas/IssueIdOrKeysAssociation' description: The result of a successful store development information request '400': description: 'Request has incorrect format. It will fail in the following cases: If no repositories or development information entities were provided, or more than 5 properties were submitted, or there are one or more properties with leading underscore ''_'' symbol in their keys.' content: application/json: schema: title: ErrorMessages type: object required: - errorMessages properties: errorMessages: type: array description: List of errors occurred. items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. description: A response returned in the case of an error. '401': description: Missing a JWT token, or token is invalid. '403': description: The JWT token used does not correspond to an app that defines the jiraDevelopmentTool module, or the app does not define the 'WRITE' scope '413': description: Data is too large. Submit fewer devinfo entities in each payload. content: application/json: schema: title: ErrorMessages type: object required: - errorMessages properties: errorMessages: type: array description: List of errors occurred. items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. description: A response returned in the case of an error. '429': description: API rate limit has been exceeded. headers: X-RateLimit-Remaining: schema: type: integer description: The number of remaining possible requests in current rate limit window. X-RateLimit-Reset: schema: type: string description: The date in ISO 8601 format when the rate limit values will be next reset. X-RateLimit-Limit: schema: type: integer description: The maximum possible requests in a window of one minute. Retry-After: schema: type: integer description: The number of seconds to wait before making a follow-up request. '500': description: An unknown error has occurred. content: application/json: schema: title: ErrorMessages type: object required: - errorMessages properties: errorMessages: type: array description: List of errors occurred. items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. description: A response returned in the case of an error. '503': description: Service is unavailable due to maintenance or other reasons. security: - basicAuth: [] - OAuth2: - write:dev-info:jira x-atlassian-data-security-policy: - app-access-rule-exempt: false x-atlassian-connect-scope: WRITE /rest/devinfo/0.10/repository/{repositoryId}: get: tags: - Development Information summary: Get repository description: For the specified repository ID, retrieves the repository and the most recent 400 development information entities. The result will be what is currently stored, ignoring any pending updates or deletes. operationId: getRepository parameters: - name: repositoryId in: path description: The ID of repository to fetch required: true schema: type: string - name: Authorization in: header description: All requests must be signed with either a Connect JWT token or OAuth token for an on-premise integration that corresponds to an app installed in Jira. If the JWT token corresponds to a Connect app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details about Connect JWT tokens. See https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/ for details about on-premise integrations. required: true schema: type: string responses: '200': description: The repository data currently stored for the given ID. content: application/json: schema: title: Repository type: object required: - id - name - updateSequenceId - url properties: name: type: string example: atlassian-connect-jira-example description: The name of this repository. Max length is 255 characters. maxLength: 255 description: type: string example: The repository which stores code of the Atlassian Connect Add-on Devinfo application. description: Description of this repository. Max length is 1024 characters. maxLength: 1024 forkOf: type: string example: 56c7c750-cee2-48e2-b920-d7706dfd11f7 description: The ID of the repository this repository was forked from, if it's a fork. Max length is 1024 characters. maxLength: 1024 url: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example description: The URL of this repository. Max length is 2000 characters. maxLength: 2000 format: url commits: type: array description: List of commits to update in this repository. Must not contain duplicate entity IDs. Maximum number of commits is 400 items: title: Commit type: object required: - id - updateSequenceId - author - authorTimestamp - displayId - fileCount - message - url properties: id: type: string example: a7727ee6350c33cdf90826dc21abaa26a5704370 description: The identifier or hash of the commit. Will be used for cross entity linking. Must be unique for all commits within a repository, i.e., only one commit can have ID 'X' in repository 'Y'. But adding, e.g., a branch with ID 'X' to repository 'Y' is acceptable. Only alphanumeric characters, and '~.-_', are allowed. Max length is 1024 characters issueKeys: type: array example: '["ISSUE-1","TEST-2"]' description: List of issues keys that this entity is associated with. They must be valid Jira issue keys. minItems: 1 maxItems: 500 pattern: ^\p{L}[\p{L}\p{Digit}_]{1,255}-\p{Digit}{1,255}$ items: type: string deprecated: true associations: description: The Jira issue keys or IDs to associate the commit with. type: array items: $ref: '#/components/schemas/IssueIdOrKeysAssociation' updateSequenceId: type: integer format: int64 example: 1523494301248 description: An ID used to apply an ordering to updates for this entity in the case of out-of-order receipt of update requests. This can be any monotonically increasing number. A suggested implementation is to use epoch millis from the provider system, but other alternatives are valid (e.g. a provider could store a counter against each entity and increment that on each update to Jira). Updates for an entity that are received with an updateSqeuenceId lower than what is currently stored will be ignored. hash: type: string description: Deprecated. Use the id field instead. maxLength: 255 flags: type: array example: '[MERGE_COMMIT]' description: The set of flags for this commit uniqueItems: true items: type: string enum: - MERGE_COMMIT message: type: string example: README.md edited online with Bitbucket description: The commit message. Max length is 1024 characters. If anything longer is supplied, it will be truncated down to 1024 characters. maxLength: 1024 author: title: Author type: object properties: name: type: string example: Jane Doe description: Deprecated. The name of this user in a format suitable for display. Max length is 255 characters. maxLength: 255 email: type: string example: jane_doe@atlassian.com description: The email address of the user. Used to associate the user with a Jira user. Max length is 255 characters. maxLength: 255 username: type: string example: jdoe description: Deprecated. The username of the user. Used to associate the user with a Jira user if there are multiple users for a given email. Max length is 255 characters. maxLength: 255 url: type: string example: https://atlassian.com/account/jane_doe description: Deprecated. The URL of the profile for this user. Max length is 2000 characters. maxLength: 2000 avatar: type: string example: https://atlassian.com/account/jane_doe/avatar/32 description: Deprecated. The URL of the avatar for this user. Max length is 2000 characters. maxLength: 2000 description: Describes the author of a particular entity fileCount: type: integer format: int32 example: 1 description: The total number of files added, removed, or modified by this commit minimum: 0 url: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/commits/a7727ee6350c33cdf90826dc21abaa26a5704370 description: The URL of this commit. Max length is 2000 characters. maxLength: 2000 format: url files: type: array description: List of file changes. Max number of files is 10. Currently, only the first 5 files are shown (sorted by path) in the UI. This UI behavior may change without notice. maxItems: 10 items: title: File type: object required: - changeType - linesAdded - linesRemoved - path - url properties: path: type: string example: /home/user/src/atlassian-connect-jira-example/README.md description: The path of the file. Max length is 1024 characters. maxLength: 1024 url: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/src/a7727ee6350c33cdf90826dc21abaa26a5704370/README.md description: The URL of this file. Max length is 2000 characters. maxLength: 2000 format: url changeType: type: string example: MODIFIED description: The operation performed on this file enum: - ADDED - COPIED - DELETED - MODIFIED - MOVED - UNKNOWN linesAdded: type: integer format: int32 example: 0 description: Number of lines added to the file minimum: 0 linesRemoved: type: integer format: int32 example: 1 description: Number of lines removed from the file minimum: 0 description: Describes changes to a file authorTimestamp: type: string example: '2016-10-31T23:27:25+00:00' description: The author timestamp of this commit. Formatted as a UTC ISO 8601 date time format. displayId: type: string example: a7727ee description: Shortened identifier for this commit, used for display. Max length is 255 characters. maxLength: 255 description: Represents a commit in the version control system. minItems: 0 maxItems: 400 branches: type: array description: List of branches to update in this repository. Must not contain duplicate entity IDs. Maximum number of branches is 400. items: title: Branch type: object required: - id - updateSequenceId - lastCommit - name - url properties: id: type: string example: c6c7c750-cee2-48e2-b920-d7706dfd11f9 description: The ID of this entity. Will be used for cross entity linking. Must be unique by entity type within a repository, i.e., only one commit can have ID 'X' in repository 'Y'. But adding, e.g., a branch with ID 'X' to repository 'Y' is acceptable. Only alphanumeric characters, and '~.-_', are allowed. Max length is 1024 characters. maxLength: 1024 issueKeys: type: array example: '["ISSUE-1","TEST-2"]' description: List of issues keys that this entity is associated with. They must be valid Jira issue keys. minItems: 1 maxItems: 500 pattern: ^\p{L}[\p{L}\p{Digit}_]{1,255}-\p{Digit}{1,255}$ items: type: string deprecated: true associations: description: The Jira issue keys or IDs to associate the branch with. type: array items: $ref: '#/components/schemas/IssueIdOrKeysAssociation' updateSequenceId: type: integer format: int64 example: 1523494301248 description: An ID used to apply an ordering to updates for this entity in the case of out-of-order receipt of update requests. This can be any monotonically increasing number. A suggested implementation is to use epoch millis from the provider system, but other alternatives are valid (e.g. a provider could store a counter against each entity and increment that on each update to Jira). Updates for an entity that are received with an updateSqeuenceId lower than what is currently stored will be ignored. name: type: string example: master description: The name of the branch. Max length is 512 characters. maxLength: 512 lastCommit: title: Commit type: object required: - id - issueKeys - updateSequenceId - author - authorTimestamp - displayId - fileCount - message - url properties: id: type: string example: a7727ee6350c33cdf90826dc21abaa26a5704370 description: The identifier or hash of the commit. Will be used for cross entity linking. Must be unique for all commits within a repository, i.e., only one commit can have ID 'X' in repository 'Y'. But adding, e.g., a branch with ID 'X' to repository 'Y' is acceptable. Only alphanumeric characters, and '~.-_', are allowed. Max length is 1024 characters issueKeys: type: array example: '["ISSUE-1","TEST-2"]' description: List of issues keys that this entity is associated with. They must be valid Jira issue keys. minItems: 1 maxItems: 500 pattern: ^\p{L}[\p{L}\p{Digit}_]{1,255}-\p{Digit}{1,255}$ items: type: string updateSequenceId: type: integer format: int64 example: 1523494301248 description: An ID used to apply an ordering to updates for this entity in the case of out-of-order receipt of update requests. This can be any monotonically increasing number. A suggested implementation is to use epoch millis from the provider system, but other alternatives are valid (e.g. a provider could store a counter against each entity and increment that on each update to Jira). Updates for an entity that are received with an updateSqeuenceId lower than what is currently stored will be ignored. hash: type: string description: Deprecated. Use the id field instead. maxLength: 255 flags: type: array example: '[MERGE_COMMIT]' description: The set of flags for this commit uniqueItems: true items: type: string enum: - MERGE_COMMIT message: type: string example: README.md edited online with Bitbucket description: The commit message. Max length is 1024 characters. If anything longer is supplied, it will be truncated down to 1024 characters. maxLength: 1024 author: title: Author type: object properties: name: type: string example: Jane Doe description: Deprecated. The name of this user in a format suitable for display. Max length is 255 characters. maxLength: 255 email: type: string example: jane_doe@atlassian.com description: The email address of the user. Used to associate the user with a Jira user. Max length is 255 characters. maxLength: 255 username: type: string example: jdoe description: Deprecated. The username of the user. Used to associate the user with a Jira user if there are multiple users for a given email. Max length is 255 characters. maxLength: 255 url: type: string example: https://atlassian.com/account/jane_doe description: Deprecated. The URL of the profile for this user. Max length is 2000 characters. maxLength: 2000 avatar: type: string example: https://atlassian.com/account/jane_doe/avatar/32 description: Deprecated. The URL of the avatar for this user. Max length is 2000 characters. maxLength: 2000 description: Describes the author of a particular entity fileCount: type: integer format: int32 example: 1 description: The total number of files added, removed, or modified by this commit minimum: 0 url: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/commits/a7727ee6350c33cdf90826dc21abaa26a5704370 description: The URL of this commit. Max length is 2000 characters. maxLength: 2000 format: url files: type: array description: List of file changes. Max number of files is 10. Currently, only the first 5 files are shown (sorted by path) in the UI. This UI behavior may change without notice. maxItems: 10 items: title: File type: object required: - changeType - linesAdded - linesRemoved - path - url properties: path: type: string example: /home/user/src/atlassian-connect-jira-example/README.md description: The path of the file. Max length is 1024 characters. maxLength: 1024 url: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/src/a7727ee6350c33cdf90826dc21abaa26a5704370/README.md description: The URL of this file. Max length is 2000 characters. maxLength: 2000 format: url changeType: type: string example: MODIFIED description: The operation performed on this file enum: - ADDED - COPIED - DELETED - MODIFIED - MOVED - UNKNOWN linesAdded: type: integer format: int32 example: 0 description: Number of lines added to the file minimum: 0 linesRemoved: type: integer format: int32 example: 1 description: Number of lines removed from the file minimum: 0 description: Describes changes to a file authorTimestamp: type: string example: '2016-10-31T23:27:25+00:00' description: The author timestamp of this commit. Formatted as a UTC ISO 8601 date time format. displayId: type: string example: a7727ee description: Shortened identifier for this commit, used for display. Max length is 255 characters. maxLength: 255 description: Represents a commit in the version control system. createPullRequestUrl: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/pull-requests/new description: The URL of the page for creating a pull request from this branch. Max length is 2000 characters. maxLength: 2000 url: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/branch/master description: The URL of the branch. Max length is 2000 characters. maxLength: 2000 description: Represents a branch in the version control system minItems: 0 maxItems: 400 pullRequests: type: array description: List of pull requests to update in this repository. Must not contain duplicate entity IDs. Maximum number of pull requests is 400 items: title: PullRequest type: object required: - id - updateSequenceId - author - commentCount - displayId - lastUpdate - sourceBranch - status - title - url properties: id: type: string example: c6c7c750-cee2-48e2-b920-d7706dfd11f9 description: The ID of this entity. Will be used for cross entity linking. Must be unique by entity type within a repository, i.e., only one commit can have ID 'X' in repository 'Y'. But adding, e.g., a branch with ID 'X' to repository 'Y' is acceptable. Only alphanumeric characters, and '~.-_', are allowed. Max length is 1024 characters issueKeys: type: array example: '["ISSUE-1","TEST-2"]' description: List of issues keys that this entity is associated with. They must be valid Jira issue keys. minItems: 1 maxItems: 500 pattern: ^\p{L}[\p{L}\p{Digit}_]{1,255}-\p{Digit}{1,255}$ items: type: string deprecated: true associations: description: The Jira issue keys or IDs to associate the pull request with. type: array items: $ref: '#/components/schemas/IssueIdOrKeysAssociation' updateSequenceId: type: integer format: int64 example: 1523494301248 description: An ID used to apply an ordering to updates for this entity in the case of out-of-order receipt of update requests. This can be any monotonically increasing number. A suggested implementation is to use epoch millis from the provider system, but other alternatives are valid (e.g. a provider could store a counter against each entity and increment that on each update to Jira). Updates for an entity that are received with an updateSqeuenceId lower than what is currently stored will be ignored. status: type: string example: OPEN description: The status of the pull request. In the case of concurrent updates, priority is given in the order OPEN, MERGED, DECLINED, UNKNOWN enum: - OPEN - MERGED - DECLINED - UNKNOWN title: type: string example: 'Pull request 2, fixing all the issues caused by pull request #1' description: Title of the pull request. Max length is 1024 characters. maxLength: 1024 author: title: Author type: object properties: name: type: string example: Jane Doe description: Deprecated. The name of this user in a format suitable for display. Max length is 255 characters. maxLength: 255 email: type: string example: jane_doe@atlassian.com description: The email address of the user. Used to associate the user with a Jira user. Max length is 255 characters. maxLength: 255 username: type: string example: jdoe description: Deprecated. The username of the user. Used to associate the user with a Jira user if there are multiple users for a given email. Max length is 255 characters. maxLength: 255 url: type: string example: https://atlassian.com/account/jane_doe description: Deprecated. The URL of the profile for this user. Max length is 2000 characters. maxLength: 2000 avatar: type: string example: https://atlassian.com/account/jane_doe/avatar/32 description: Deprecated. The URL of the avatar for this user. Max length is 2000 characters. maxLength: 2000 description: Describes the author of a particular entity commentCount: type: integer format: int32 example: 42 description: The number of comments on the pull request sourceBranch: type: string example: ISSUE-1-feature-branch description: The name of the source branch of this PR. Max length is 255 characters. maxLength: 255 sourceBranchUrl: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/branch/ISSUE-1-feature-branch description: The url of the source branch of this PR. This is used to match this PR against the branch. Max length is 2000 characters. maxLength: 2000 format: url lastUpdate: type: string example: '2016-10-31T23:27:25+00:00' description: The most recent update to this PR. Formatted as a UTC ISO 8601 date time format. destinationBranch: type: string example: master description: The name of destination branch of this PR. Max length is 255 characters. maxLength: 255 destinationBranchUrl: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/src/master description: The url of the destination branch of this PR. Max length is 2000 characters. maxLength: 2000 format: url reviewers: type: array description: The list of reviewers of this pull request items: title: Reviewer type: object properties: name: type: string example: Jane Doe description: Deprecated. The name of this reviewer. Max length is 255 characters. maxLength: 255 approvalStatus: type: string example: APPROVED description: The approval status of this reviewer, default is UNAPPROVED. enum: - APPROVED - UNAPPROVED url: type: string example: https://atlassian.com/account/jane_doe description: Deprecated. The URL of the profile for this reviewer. Max length is 2000 characters. maxLength: 2000 format: url avatar: type: string example: https://atlassian.com/account/jane_doe/avatar/32 description: Deprecated. The URL of the avatar for this reviewer. Max length is 2000 characters. maxLength: 2000 format: url email: type: string example: jane_doe@example.com description: The email address of this reviewer. Max length is 254 characters. maxLength: 254 accountId: type: string example: 655363:e4ca5e2d-a901-40e3-877e-bf5d22c0f130 description: The Atlassian Account ID (AAID) of this reviewer. Max length is 128 characters. maxLength: 128 description: The reviewer of a pull request url: type: string example: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/pull-requests/2 description: The URL of this pull request. Max length is 2000 characters. maxLength: 2000 format: url displayId: type: string example: Pull request 2 description: Shortened identifier for this pull request, used for display. Max length is 255 characters. maxLength: 255 description: Represents a pull request minItems: 0 maxItems: 400 avatar: type: string example: http://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/avatar/32 description: The URL of the avatar for this repository. Max length is 2000 characters. maxLength: 2000 format: url avatarDescription: type: string example: Avatar description description: Description of the avatar for this repository. Max length is 1024 characters. maxLength: 1024 id: type: string example: c6c7c750-cee2-48e2-b920-d7706dfd11f9 description: The ID of this entity. Will be used for cross entity linking. Must be unique by entity type within a repository, i.e., only one commit can have ID 'X' in repository 'Y'. But adding, e.g., a branch with ID 'X' to repository 'Y' is acceptable. Only alphanumeric characters, and '~.-_', are allowed. Max length is 1024 characters. maxLength: 1024 updateSequenceId: type: integer format: int64 example: 1523494301248 description: ' An ID used to apply an ordering to updates for this entity in the case of out-of-order receipt of update requests. This can be any monotonically increasing number. A suggested implementation is to use epoch millis from the provider system, but other alternatives are valid (e.g. a provider could store a counter against each entity and increment that on each update to Jira). Updates for an entity that are received with an updateSqeuenceId lower than what is currently stored will be ignored.' description: Represents a repository, containing development information such as commits, pull requests, and branches. '401': description: Missing a JWT token, or token is invalid. '403': description: The JWT token used does not correspond to an app that defines the jiraDevelopmentTool module, or the app does not define the 'READ' scope '404': description: No data found for the given repository ID. '429': description: API rate limit has been exceeded. '500': description: An unknown error has occurred. content: application/json: schema: title: ErrorMessages type: object required: - errorMessages properties: errorMessages: type: array description: List of errors occurred. items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. description: A response returned in the case of an error. '503': description: Service is unavailable due to maintenance or other reasons. security: - basicAuth: [] - OAuth2: - read:dev-info:jira x-atlassian-data-security-policy: - app-access-rule-exempt: false x-atlassian-connect-scope: READ delete: tags: - Development Information summary: Delete repository description: Deletes the repository data stored by the given ID and all related development information entities. Deletion is performed asynchronously. operationId: deleteRepository parameters: - name: repositoryId in: path description: The ID of repository to delete required: true schema: type: string - name: _updateSequenceId in: query description: 'An optional property to use to control deletion. Only stored data with an updateSequenceId less than or equal to that provided will be deleted. This can be used to help ensure submit/delete requests are applied correctly if they are issued close together. ' required: false schema: type: integer format: int64 - name: Authorization in: header description: All requests must be signed with either a Connect JWT token or OAuth token for an on-premise integration that corresponds to an app installed in Jira. If the JWT token corresponds to a Connect app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details about Connect JWT tokens. See https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/ for details about on-premise integrations. required: true schema: type: string responses: '202': description: Delete request has been accepted. Data will eventually be removed from Jira if it exists. '401': description: Missing a JWT token, or token is invalid. '403': description: The JWT token used does not correspond to an app that defines the jiraDevelopmentTool module, or the app does not define the 'DELETE' scope '429': description: API rate limit has been exceeded. '500': description: An unknown error has occurred. content: application/json: schema: title: ErrorMessages type: object required: - errorMessages properties: errorMessages: type: array description: List of errors occurred. items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. description: A response returned in the case of an error. '503': description: Service is unavailable due to maintenance or other reasons. security: - basicAuth: [] - OAuth2: - delete:dev-info:jira x-atlassian-data-security-policy: - app-access-rule-exempt: false x-atlassian-connect-scope: DELETE /rest/devinfo/0.10/bulkByProperties: delete: tags: - Development Information summary: Delete development information by properties description: 'Deletes development information entities which have all the provided properties. Repositories which have properties that match ALL of the properties (i.e. treated as an AND), and all their related development information (such as commits, branches and pull requests), will be deleted. For example if request is `DELETE bulk?accountId=123&projectId=ABC` entities which have properties `accountId=123` and `projectId=ABC` will be deleted. Optional param `_updateSequenceId` is no longer supported. Deletion is performed asynchronously: specified entities will eventually be removed from Jira.' operationId: deleteByProperties parameters: - name: Authorization in: header description: All requests must be signed with either a Connect JWT token or OAuth token for an on-premise integration that corresponds to an app installed in Jira. If the JWT token corresponds to a Connect app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details about Connect JWT tokens. See https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/ for details about on-premise integrations. required: true schema: type: string - name: _updateSequenceId in: query description: 'An optional property to use to control deletion. Only stored data with an updateSequenceId less than or equal to that provided will be deleted. This can be used to help ensure submit/delete requests are applied correctly if they are issued close together. ' required: false schema: type: integer format: int64 responses: '202': description: 'Delete accepted. Data will eventually be removed from Jira. ' '400': description: 'Request has incorrect format. It will fail in the following cases: If no query properties are specified. If `_updateSequenceId` is not a numeric value. If multiple values of the same property key are specified. Deleting data for many property values, for the same property key, requires multiple requests to this resource. ' content: application/json: schema: title: ErrorMessages type: object required: - errorMessages properties: errorMessages: type: array description: List of errors occurred. items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. description: A response returned in the case of an error. '401': description: Missing a JWT token, or token is invalid. '403': description: The JWT token used does not correspond to an app that defines the jiraDevelopmentTool module, or the app does not define the 'DELETE' scope '429': description: API rate limit has been exceeded. '500': description: An unknown error has occurred. content: application/json: schema: title: ErrorMessages type: object required: - errorMessages properties: errorMessages: type: array description: List of errors occurred. items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. description: A response returned in the case of an error. '503': description: Service is unavailable due to maintenance or other reasons. security: - basicAuth: [] - OAuth2: - delete:dev-info:jira x-atlassian-data-security-policy: - app-access-rule-exempt: false x-atlassian-connect-scope: DELETE /rest/devinfo/0.10/existsByProperties: get: tags: - Development Information summary: Check if data exists for the supplied properties description: Checks if repositories which have all the provided properties exists. For example, if request is `GET existsByProperties?accountId=123&projectId=ABC` then result will be positive only if there is at least one repository with both properties `accountId=123` and `projectId=ABC`. Special property `_updateSequenceId` can be used to filter all entities with updateSequenceId less or equal than the value specified. In addition to the optional `_updateSequenceId`, one or more query params must be supplied to specify properties to search by. operationId: existsByProperties parameters: - name: Authorization in: header description: All requests must be signed with either a Connect JWT token or OAuth token for an on-premise integration that corresponds to an app installed in Jira. If the JWT token corresponds to a Connect app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details about Connect JWT tokens. See https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/ for details about on-premise integrations. required: true schema: type: string - name: _updateSequenceId in: query description: 'An optional property. Filters out entities and repositories which have updateSequenceId greater than specified. ' required: false schema: type: integer format: int64 responses: '200': description: 'Returns whether data exists for the specified properties. ' content: application/json: schema: title: ExistsForPropertiesResponse type: object properties: hasDataMatchingProperties: type: boolean description: Whether there is data matching the query readOnly: true description: Whether there is data for the properties supplied in a query '400': description: 'Request has incorrect format. It will fail in the following cases: If no query properties are specified. If `_updateSequenceId` is not a numeric value. If multiple values of the same property key are specified. ' content: application/json: schema: title: ErrorMessages type: object required: - errorMessages properties: errorMessages: type: array description: List of errors occurred. items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. description: A response returned in the case of an error. '401': description: Missing a JWT token, or token is invalid. '403': description: The JWT token used does not correspond to an app that defines the jiraDevelopmentTool module, or the app does not define the 'READ' scope '429': description: API rate limit has been exceeded. '500': description: An unknown error has occurred. content: application/json: schema: title: ErrorMessages type: object required: - errorMessages properties: errorMessages: type: array description: List of errors occurred. items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. description: A response returned in the case of an error. '503': description: Service is unavailable due to maintenance or other reasons. security: - basicAuth: [] - OAuth2: - read:dev-info:jira x-atlassian-data-security-policy: - app-access-rule-exempt: false x-atlassian-connect-scope: READ /rest/devinfo/0.10/repository/{repositoryId}/{entityType}/{entityId}: delete: tags: - Development Information summary: Delete development information entity description: Deletes particular development information entity. Deletion is performed asynchronously. operationId: deleteEntity parameters: - name: repositoryId in: path required: true schema: type: string - name: entityType in: path required: true schema: type: string enum: - commit - branch - pull_request - name: entityId in: path required: true schema: type: string - name: _updateSequenceId in: query description: 'An optional property to use to control deletion. Only stored data with an updateSequenceId less than or equal to that provided will be deleted. This can be used to help ensure submit/delete requests are applied correctly if they are issued close together. ' required: false schema: type: integer format: int64 - name: Authorization in: header description: All requests must be signed with either a Connect JWT token or OAuth token for an on-premise integration that corresponds to an app installed in Jira. If the JWT token corresponds to a Connect app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details about Connect JWT tokens. See https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/ for details about on-premise integrations. required: true schema: type: string responses: '202': description: Delete request has been accepted. Data will eventually be removed from Jira if it exists. '400': description: Wrong entity type specified content: application/json: schema: title: ErrorMessages type: object required: - errorMessages properties: errorMessages: type: array description: List of errors occurred. items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. description: A response returned in the case of an error. '401': description: Missing a JWT token, or token is invalid. '403': description: The JWT token used does not correspond to an app that defines the jiraDevelopmentTool module, or the app does not define the 'DELETE' scope '429': description: API rate limit has been exceeded. '500': description: An unknown error has occurred. content: application/json: schema: title: ErrorMessages type: object required: - errorMessages properties: errorMessages: type: array description: List of errors occurred. items: title: ErrorMessage type: object required: - message properties: message: type: string description: A human-readable message describing the error. errorTraceId: type: string description: An optional trace ID that can be used by Jira developers to locate the source of the error. description: A message supplied in the case of an error. description: A response returned in the case of an error. '503': description: Service is unavailable due to maintenance or other reasons. security: - basicAuth: [] - OAuth2: - delete:dev-info:jira x-atlassian-data-security-policy: - app-access-rule-exempt: false x-atlassian-connect-scope: DELETE components: schemas: IssueIdOrKeysAssociation: description: 'An association type referencing issues in Jira. ' required: - associationType - values type: object properties: associationType: description: 'Defines the association type. ' type: string enum: - issueKeys - issueIdOrKeys example: issueIdOrKeys values: description: '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. ' type: array items: description: 'An issue key or ID that references an issue in Jira. ' type: string pattern: (\w{1,255}-\d{1,255}|\d{1,255}) example: ABC-123 minItems: 1 maxItems: 500 example: associationType: issueIdOrKeys values: - ABC-123 - ABC-456 securitySchemes: OAuth2: description: OAuth2 scopes for Jira flows: authorizationCode: authorizationUrl: https://auth.atlassian.com/authorize scopes: delete:board-scope.admin:jira-software: Remove board configuration, features, and properties. delete:sprint:jira-software: Delete sprints and their properties. manage:jira-configuration: Configure Jira settings that require the Jira administrators permission, for example, create projects and custom fields, view workflows, manage issue link types. manage:jira-project: Create and edit project settings and create new project-level objects, for example, versions, components. manage:jira-webhook: Manage Jira webhooks. Enables an OAuth app to register and unregister dynamic webhooks in Jira. It also provides for fetching of registered webhooks. read:board-scope.admin:jira-software: View configuration, features, filters, project, properties and quick filters related to the given board. read:board-scope:jira-software: View board and issues from a board, view issues from a backlog and view reports and versions. read:build:jira-software: View builds. read:deployment:jira-software: View deployments. read:epic:jira-software: View and search for epics, view issues related to an epic and issues without an epic. read:feature-flag:jira-software: View feature flags. read:issue:jira-software: View issues, issue estimations and field used for estimations. read:jira-user: View user information in Jira that you have access to, including usernames, email addresses, and avatars. read:jira-work: Read project and issue data. Search for issues and objects associated with issues (such as attachments and worklogs). read:remote-link:jira-software: View remote links. read:source-code:jira-software: View repositories and check if data exists for the supplied properties. read:sprint:jira-software: View sprints and sprint related issues and properties. write:board-scope.admin:jira-software: Create board, toggle features and set and delete properties. write:board-scope:jira-software: Move issues to a backlog and move issues from a backlog to a board. write:build:jira-software: Submit and delete build. write:deployment:jira-software: Submit and delete deployment. write:epic:jira-software: Remove issues from epic, move issues to epic, rank epics and partially update epics. A partial update means that fields not present in the request JSON will not be updated. write:feature-flag:jira-software: Submit and delete feature flag. write:issue:jira-software: Move (rank) issues and update estimation of the issue. write:jira-work: Create and edit issues in Jira, post comments, create worklogs, and delete issues. write:remote-link:jira-software: Submit and delete remote link. write:source-code:jira-software: Store and delete development information, delete repository and delete development information entity. write:sprint:jira-software: Save, move issues to sprints, and change the order of sprints. read:dev-info:jira: Read development information write:dev-info:jira: Write development information delete:dev-info:jira: Delete development information read:feature-flag-info:jira: Read feature flag information write:feature-flag-info:jira: Write feature flag information delete:feature-flag-info:jira: Delete feature flag information read:deployment-info:jira: Read deployment information write:deployment-info:jira: Write deployment information delete:deployment-info:jira: Delete deployment information read:build-info:jira: Read build information write:build-info:jira: Write build information delete:build-info:jira: Delete build information read:remote-link-info:jira: Read remote link information write:remote-link-info:jira: Write remote link information delete:remote-link-info:jira: Delete remote link information read:security:jira: Read security information write:security:jira: Write security information delete:security:jira: Delete security information tokenUrl: https://auth.atlassian.com/oauth/token type: oauth2 basicAuth: description: Basic authentication using email and API token scheme: basic type: http externalDocs: description: Find out more about Atlassian products and services. url: http://www.atlassian.com x-atlassian-narrative: documents: - anchor: introduction body: "Welcome to the Jira Software Cloud REST API reference. You can use this REST API to build add-ons for Jira Software,\ndevelop integrations between Jira Software and other applications, or script interactions with Jira Software. This page\ndocuments the REST resources available in Jira Software Cloud, along with expected HTTP response codes and sample\nrequests.\n\nJira Software is built on the Jira platform. As such, there is an overlap in functionality\nbetween what is provided by Jira Software and what is provided by the Jira platform. The REST API reference for the\nJira Cloud platform is here: [Jira Cloud platform REST API](https://developer.atlassian.com/cloud/jira/platform/rest).\n\n## Authentication\n\n### Authentication for Atlassian Connect add-ons\n\nIf you are integrating with the Jira REST APIs via an Atlassian Connect add-on, API calls are authenticated via JWT\n(JSON Web Tokens). This is built into the supported Atlassian Connect libraries. At a high level, authentication works\nby the add-on exchanging a security context with the application. This context is used to create and validate JWT\ntokens, embedded in API calls. To learn more, read the [Atlassian Connect authentication documentation](https://developer.atlassian.com/cloud/jira/platform/authentication-for-apps/).\n\nSome integration APIs such as [Feature Flags](#api-group-Feature-Flags) are only available to Atlassian Connect apps that\ndefine the relevant [module](https://developer.atlassian.com/cloud/jira/platform/about-jira-modules/) related to that API.\nOther APIs, such as the [Development Information](#api-group-Development-Information), [Builds](#api-group-Builds), and [Deployments](#api-group-Deployments) APIs\nare available to both Atlassian Connect apps and on-premises tools using Jira Software's\n[OAuth credentials](https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/) for system-to-system integration.\n\n### Authentication for REST API requests\n\nIf you are integrating directly with the REST APIs, rather than via an Atlassian Connect add-on, use one of the\nauthentication methods listed below:\n* [OAuth 2.0](https://developer.atlassian.com/cloud/jira/software/scopes-for-oauth-2-3LO-and-forge-apps/) -\n This token-based method is the recommended method. It is more flexible and secure than other options.\n * [OAuth 1.0a](https://developer.atlassian.com/cloud/jira/platform/jira-rest-api-oauth-authentication) -\n This is a legacy authentication method and, therefore, isn't recommended. Instead use OAuth 2.0.\n * [Basic HTTP](https://developer.atlassian.com/cloud/jira/platform/jira-rest-api-basic-authentication/) -\n This method is only recommended for tools like scripts or bots. It is easier to implement, but much less secure.\n\nNote, Jira itself uses cookie-based authentication in the browser, so you can call REST from Javascript on the page and\nrely on the authentication that the browser has established. To reproduce the behavior of the Jira log-in page (for\nexample, to display authentication error messages to users) can `POST` to the `/auth/1/session` [resource](https://docs.atlassian.com/jira/REST/cloud/#auth/1/session).\n\n### Authentication for on-premises integrations\n\nIf you are integrating an on-premises app with the Jira REST APIs, API calls are authenticated via an OAuth token.\nTo obtain a token, create a set of OAuth credentials with permissions for the APIs that app needs to access.\nUse the credentials to request a token by calling `https://api.atlassian.com/oauth/token`.\nSee [Integrating Jira Software Cloud with on-premises tools](https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/) for details.\nNote that only the [Development Information](#api-group-Development-Information), [Builds](#api-group-Builds), and [Deployments](#api-group-Deployments) APIs are currently available for on-premises integrations.\nTo simplify development, we have a separate [downloadable API spec](https://developer.atlassian.com/cloud/jira/software/on-premise-swagger.json).\n\nAtlassian has developed an [open source plugin for Jenkins](https://github.com/jenkinsci/atlassian-jira-software-cloud-plugin), which you can use to bootstrap development.\nThis plugin uses the authentication method described above and calls the Builds and Deployments APIs.\n\n\n#### Base URL differences\n\nWhen building an on-premises integration, the base URL for API operations is different to the base URL used for Connect apps. This is because requests from on-premises integrations (OAuth) need to be sent via the Atlassian API proxy at `https://api.atlassian.com`.\n\nThis document does not display the base URLs used by on-premises integrations. Therefore, when using an operation, you must replace `https://your-domain.atlassian.net/rest/{type}/{version}/{operation}`\nwith `https://api.atlassian.com/jira/{type}/{version}/cloud/{cloudId}/{operation}`.\n\nFor example:\n* Builds API: Change the path from `https://your-domain.atlassian.net/rest/builds/0.1/bulk` to `https://api.atlassian.com/jira/builds/0.1/cloud/{cloudId}/bulk`.\n* Development Information: Change the path from `https://your-domain.atlassian.net/rest/devinfo/0.10/bulk` to `https://api.atlassian.com/jira/devinfo/0.1/cloud/{cloudId}/bulk`. Note the version change.\n* Deployments: Change the path from `https://your-domain.atlassian.net/rest/deployments/0.1/bulk` to `https://api.atlassian.com/jira/deployments/0.1/cloud/{cloudId}/bulk`.\n\nNote, get the `cloudId` for a Jira instance by calling `https://your-domain.atlassian.net/_edge/tenant_info`.\n\n\n## URI structure\n\nJira Agile's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application\nwill make an HTTP request and parse the response. The Jira Agile REST API uses [JSON](http://en.wikipedia.org/wiki/JSON)\nas its communication format, and the standard HTTP methods like `GET`, `PUT`, `POST` and `DELETE` (see API descriptions\nbelow for which methods are available for each resource). URIs for Jira Agile's REST API resource have the following\nstructure:\n\n http://host:port/context/rest/api-name/api-version/resource-name\n\nCurrently there are two API names available, which will be discussed further below:\n\n * `auth` - for authentication-related operations, and\n * `api` - for everything else.\n\nThe current API version is `1`. However, there is also a symbolic version, called `latest`, which resolves to the\nlatest version supported by the given Jira Software Cloud instance. For example, if you wanted to retrieve the JSON\nrepresentation of a board with `boardId=123`, from a Jira Software Cloud instance at `https://jira.atlassian.net`, you\nwould access:\n\n https://jira.atlassian.net/rest/agile/latest/board/123\n\n## Pagination\n\nPagination is used for the Jira REST APIs to conserve server resources and limit response size for resources that\nreturn potentially large collection of items. A request to a pages API will result in a values array wrapped in a JSON\nobject with some paging metadata, like this:\n\n#### Request\n\n http://host:port/context/rest/api-name/api-version/resource-name?startAt=0&maxResults=10\n\n#### Response\n\n```javascript\n{\n \"startAt\" : 0,\n \"maxResults\" : 10,\n \"total\": 200,\n \"values\": [\n { /* result 0 */ },\n { /* result 1 */ },\n { /* result 2 */ }\n ]\n}\n```\n\n * `startAt` - the item used as the first item in the page of results.\n * `maxResults` - how many results to return per page.\n * `total` - the number of items that the calling user has permissions for. This number *may change* while the client requests the next pages. A client should always assume that the requested page can be empty. REST API consumers should also consider the field to be optional. This value may not be included in the response, if it is too expensive to calculate.\n\nClients can use the `startAt`, `maxResults`, and `total` parameters to retrieve the desired number of results. Note,\neach API resource or method may have a different limit on the number of items returned, which means you can ask for\nmore than you are given. The actual number of items returned is an implementation detail and this can be changed over\ntime.\n\n## Experimental methods\n\nMethods marked as experimental may change without an earlier notice. We are looking for your feedback for these methods.\n\n## Query parameters\n\nAll query parameters for the resources described below are optional, unless specified otherwise.\n\n## Special Request and Response headers\n\n - **X-Atlassian-Token** (request): Operations that accept multipart/form-data must include the `X-Atlassian-Token: no-check` header in requests.\nOtherwise the request will be blocked by XSRF protection.\n- **X-AACCOUNTID** (response): This response header contains the Atlassian account ID of the authenticated user.\n\n## Jira Software field input formats\n\nJira Software provides a number of custom fields, which are made available in the Jira platform REST API. The custom\nfields are: `Sprint`, `Epic link`, `Epic name`, and `Story points`.\n\nYou can read and edit these custom fields via the [issue resource](https://docs.atlassian.com/jira/REST/cloud/#api/2/issue)\nof the Jira Platform REST API. In order to identify the custom field that you want to read or edit, you'll need the\ncustom field id. To obtain the custom field id, retrieve the list of fields from the [fields resource](https://docs.atlassian.com/jira/REST/latest/#api/2/field-getFields)\nand search for the custom field. It's better to find the field based on the schema where possible (e.g. the Sprint\nfield is identified by \"`com.pyxis.greenhopper.jira:gh-sprint`\"), as custom field names are mutable. The custom field\nid will be in the id, (e.g. `id: customfield_10007`).\n\nIf you only need to get the value of the custom field for a single issue, you may want to use the [issue resource](https://docs.atlassian.com/jira-software/REST/cloud/#agile/1.0/issue-getIssue)\nprovided by the Jira Software REST API instead. This resource returns the issue with all Jira Software-specific fields,\nincluding the fields listed above. These fields will also be formatted as proper fields with keys, in the response.\n\nNote, Jira Software also has a number of internal custom fields, which are: `Epic Color`, `Epic Status`, `Flag`, `Rank`.\nThese internal fields shouldn't be read or updated using the REST API and are not documented below.\n\n##### Sprint custom field\n\nThe Sprint custom field contains a list of sprints for a given issue. This list includes the active/future sprint that\nthe issue is currently in, as well as any closed sprints that the issue was in previously.\n\nFor legacy reasons, the [Get issue (Jira platform) method](https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-getIssue)\nreturns the Sprint custom field with sprints in a `toString` format, which is difficult to parse. See the example below.\n\n_**Deprecation notice:** The `toString` representation of sprints in the Sprint custom field that is returned by Get\nissue (Jira platform) will soon be removed. See the [notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-tostring-representation-of-sprints-in-get-issue-response/)._\n\n###### Example - Get issue (Jira platform) response\n\n```javascript\ncustomfield_11458\": [\n \"com.atlassian.greenhopper.service.sprint.Sprint@1bf75fd[id=1,rapidViewId=1,state=CLOSED,name=Sprint 1,goal=Sprint 1 goal,startDate=2016-06-06T21:30:53.537+10:00,endDate=2016-06-20T21:30:00.000+10:00,completeDate=2016-06-06T21:30:57.523+10:00,sequence=1]\",\n \"com.atlassian.greenhopper.service.sprint.Sprint@1689feb[id=2,rapidViewId=1,state=FUTURE,name=Sprint 2,goal=Sprint 2 goal,startDate=,endDate=,completeDate=,sequence=2]\"\n]\n```\n\nIf you want to parse the sprint information, use either the [Get issue (Jira Software) method](https://docs.atlassian.com/jira-software/REST/cloud/#agile/1.0/issue-getIssue)\nor [Get issue (Jira platform) method](https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-getIssue) with expanded\n`versionedRepresentations` instead, both of which return sprints in a proper format. See the example below.\n\n###### Example - Get issue (Jira platform) response with expanded versionedRepresentations\n\n```javascript\n\"customfield_10021\": {\n \"1\": [\n \"com.atlassian.greenhopper.service.sprint.Sprint@1bf75fd[id=1,rapidViewId=1,state=CLOSED,name=Sprint 1,goal=Sprint 1 goal,startDate=2016-06-06T21:30:53.537+10:00,endDate=2016-06-20T21:30:00.000+10:00,completeDate=2016-06-06T21:30:57.523+10:00,sequence=1]\",\n \"com.atlassian.greenhopper.service.sprint.Sprint@1689feb[id=2,rapidViewId=1,state=FUTURE,name=Sprint 2,goal=Sprint 2 goal,startDate=,endDate=,completeDate=,sequence=2]\"\n ],\n \"2\": [\n {\n \"id\": 1,\n \"name\": \"Sprint 1\",\n \"state\": \"closed\",\n \"boardId\": 1\n },\n {\n \"id\": 2,\n \"name\": \"Sprint 2\",\n \"state\": \"future\",\n \"boardId\": 1\n }\n ]\n}\n```\n\nIf you want to update a sprint, you need to know the sprint id, which is a number. See the example below. Note, an\nissue can only be in one active or future sprint at a time, and only the active/future sprint can edited.\n\n###### Example - Update issue request\n\n```javascript\n\"customfield_10021\": 2\n```\n\n##### Epic link custom field\n\nThe Epic link custom field contains the key of an epic that a given issue belongs to. Be aware that only the issue key\nof the existing epic can be set. Also, the Epic link cannot be set for sub-tasks and epics.\n\n###### Example\n\n```javascript\n\"customfield_11458\": \"EPIC-1\"\n```\n\n##### Epic Name\n\nThe Epic name custom field contains the name of an epic that a given issue belongs to. Be aware that only the issue key\nof the existing epic can be set. Also, the epic link cannot be set for sub-tasks and epics.\n\n###### Example\n\n```javascript\n\"customfield_11410\": \"Epic Name\"\n```\n\n##### Estimation\n\nJira Software provides a `Story Points` custom field, however the field is just a regular numeric field. The type of\nestimation and field used for estimation is determined by the board configuration. You can get this from the\n[board configuration resource](https://docs.atlassian.com/jira-software/REST/cloud/#agile/1.0/board-getConfiguration).\nNote that if the estimation field is not on a screen, it cannot be edited, and you should use the\n[Estimate issue for board method](https://docs.atlassian.com/jira-software/REST/cloud/#agile/1.0/issue-estimateIssueForBoard) instead.\n" title: Introduction