{ "openapi": "3.0.0", "info": { "description": "Jira Software Cloud REST API documentation for on-premise integrations", "version": "1001.0.0", "title": "Jira Software Cloud API", "termsOfService": "http://atlassian.com/terms/", "contact": { "url": "https://getsupport.atlassian.com" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } }, "externalDocs": { "description": "Find out more about Atlassian things", "url": "https://www.atlassian.com" }, "x-atlassian-narrative": { "documents": [ { "title": "Introduction", "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**NOTE:** Personal data that is used to identify users, such as `username` and `userKey`, has been \nremoved from the Jira Cloud REST APIs. In addition, other personal data (for example, email) is now restricted by a \nuser's profile settings (or in the case of managed accounts, the visibility settings decided by the site administrator). \nYou must update your apps to accommodate these changes, if you have not done so already. This change was previously \nannounced on 01 October 2018 and followed by a deprecation period \n(see the [announcement](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/)).\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\n * [OAuth (1.0a)](https://developer.atlassian.com/cloud/jira/platform/jira-rest-api-oauth-authentication) -\n This token-based method is the recommended method. It is more flexible and secure than other options.\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.\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" } ] }, "tags": [ { "name": "Builds", "description": "APIs related to integrating builds data with Jira Software. These APIs are only available to OAuth apps created in the Jira admin screen. See [here](https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/)" }, { "name": "Deployments", "description": "APIs related to integrating deployments data with Jira Software. These APIs are only available to OAuth apps created in the Jira admin screen. See [here](https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/)" }, { "name": "Development Information", "description": "APIs related to integrating development information (commits, branches and pull requests) with Jira. These APIs are only available to OAuth apps created in the Jira admin screen. See [here](https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/)" } ], "paths": { "/rest/builds/0.1/bulk": { "post": { "operationId": "submitBuilds", "summary": "Submit build data", "tags": [ "Builds" ], "description": "Update / insert builds data.\n\nBuilds are identified by the combination of `pipelineId` and `buildNumber`, and existing build data for the same\nbuild will be replaced if it exists and the `updateSequenceNumber` of the existing data is less than the\nincoming data.\n\nSubmissions are performed asynchronously. Submitted data will eventually be available in Jira; most updates are\navailable within a short period of time, but may take some time during peak load and/or maintenance times.\nThe `getBuildByKey` operation can be used to confirm that data has been stored successfully (if needed).\n\nIn the case of multiple builds being submitted in one request, each is validated individually prior to\nsubmission. Details of which build failed submission (if any) are available in the response object.\n\nOnly on-premise integrations, can access this resource.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBuildsRequest" } } }, "description": "Builds data to submit.\n", "required": true }, "responses": { "202": { "description": "Submission accepted. Each submitted build that is of a valid format will be eventually available in Jira.\n\nDetails of which builds were submitted and which failed submission (due to data format problems etc.)\nare available in the response object.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBuildsResponse" } } } }, "400": { "description": "Request has incorrect format.\n\nNote that in the case of an individual build having an invalid format (rather than the request as a whole)\nthe response for the request will be a 202 and details of the invalid build will be contained in the\nresponse object.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } }, "401": { "description": "Missing a OAuth token, or token is invalid.\n" }, "403": { "description": "The OAuth token used does not correspond to an app that defines the `build` permission." }, "413": { "description": "Data is too large. Submit fewer builds in each payload.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } }, "429": { "description": "API rate limit has been exceeded.\n" }, "503": { "description": "Service is unavailable due to maintenance or other reasons.\n" }, "default": { "description": "An unknown error has occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } } } } }, "/rest/builds/0.1/bulkByProperties": { "delete": { "operationId": "deleteBuildsByProperty", "summary": "Delete builds by Property", "tags": [ "Builds" ], "description": "Bulk delete all builds data that match the given request.\n\nIn addition to the optional `_updateSequenceNumber`, one or more query params must be supplied to specify\nProperties to delete by. If more than one Property is provided, data will be deleted that matches ALL of the\nProperties (e.g. treated as an AND).\n\nSee the documentation for the `submitBuilds` operation for more details.\n\ne.g. DELETE /bulkByProperties?accountId=account-123&repoId=repo-345\n\nDeletion is performed asynchronously. The `getBuildByKey` operation can be used to confirm that data has been\ndeleted successfully (if needed).\n\nOnly on-premise integrations apps that define the `build` permission can access this resource.", "parameters": [ { "name": "_updateSequenceNumber", "in": "query", "description": "An optional `updateSequenceNumber` to use to control deletion.\n\nOnly stored data with an `updateSequenceNumber` less than or equal to that provided will be deleted.\nThis can be used help ensure submit/delete requests are applied correctly if issued close together.\n\nIf not provided, all stored data that matches the request will be deleted.\n", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "202": { "description": "Delete accepted. Data will eventually be removed from Jira.\n" }, "400": { "description": "Request has incorrect format (e.g. missing at least one Property param).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } }, "401": { "description": "Missing a token, or token is invalid.\n" }, "403": { "description": "The OAuth token used does not correspond to an app that defines the `build` permission." }, "429": { "description": "API rate limit has been exceeded.\n" }, "503": { "description": "Service is unavailable due to maintenance or other reasons.\n" }, "default": { "description": "An unknown error has occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } } } } }, "/rest/builds/0.1/pipelines/{pipelineId}/builds/{buildNumber}": { "get": { "operationId": "getBuildByKey", "summary": "Get a build by key", "tags": [ "Builds" ], "description": "Retrieve the currently stored build data for the given `pipelineId` and `buildNumber` combination.\n\nThe result will be what is currently stored, ignoring any pending updates or deletes.\nOnly on-premise integrations apps that define the `build` permission can access this resource.", "parameters": [ { "name": "pipelineId", "in": "path", "description": "The `pipelineId` of the build.\n", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "buildNumber", "in": "path", "description": "The `buildNumber` of the build.\n", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "The build data currently stored for the given key.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildData" } } } }, "401": { "description": "Missing a OAuth token, or token is invalid.\n" }, "403": { "description": "The OAuth token used does not correspond to an app that defines the `build` permission." }, "404": { "description": "No build data found for the given key.\n" }, "429": { "description": "API rate limit has been exceeded.\n" }, "503": { "description": "Service is unavailable due to maintenance or other reasons.\n" }, "default": { "description": "An unknown error has occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } } } }, "delete": { "operationId": "deleteBuildByKey", "summary": "Delete a build by key", "tags": [ "Builds" ], "description": "Delete the build data currently stored for the given `pipelineId` and `buildNumber` combination.\n\nDeletion is performed asynchronously. The `getBuildByKey` operation can be used to confirm that data has been\ndeleted successfully (if needed).\n Only on-premise integrations apps that define the `build` permission can access this resource.", "parameters": [ { "name": "pipelineId", "in": "path", "description": "The `pipelineId` of the build to delete.\n", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "buildNumber", "in": "path", "description": "The `buildNumber` of the build to delete.\n", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "_updateSequenceNumber", "in": "query", "description": "An optional `updateSequenceNumber` to use to control deletion.\n\nOnly stored data with an `updateSequenceNumber` less than or equal to that provided will be deleted.\nThis can be used help ensure submit/delete requests are applied correctly if issued close together.\n", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "202": { "description": "Delete has been accepted. Data will eventually be removed from Jira if it exists.\n" }, "401": { "description": "Missing a OAuth token, or token is invalid.\n" }, "403": { "description": "The OAuth token used does not correspond to an app that defines the `build` permission." }, "429": { "description": "API rate limit has been exceeded.\n" }, "503": { "description": "Service is unavailable due to maintenance or other reasons.\n" }, "default": { "description": "An unknown error has occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } } } } }, "/jira/devinfo/0.1/cloud/{cloudId}/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": "cloudId", "in": "path", "description": "The cloud ID of the site. This can be retrieved by using http://your-site.atlassian.net/_edge/tenant_info", "required": true, "schema": { "type": "string" } } ], "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": { "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": { "type": "object", "properties": { "commits": { "type": "array", "description": "Commits ids", "items": { "type": "string" } }, "branches": { "type": "array", "description": "Branches ids", "items": { "type": "string" } }, "pullRequests": { "type": "array", "description": "Pull requests 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": { "type": "object", "properties": { "errorMessages": { "type": "array", "description": "Repository errors", "items": { "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": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Entity id" }, "errorMessages": { "type": "array", "description": "Error message", "items": { "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 error happened with particular entity" } }, "branches": { "type": "array", "description": "Branches errors", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Entity id" }, "errorMessages": { "type": "array", "description": "Error message", "items": { "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 error happened with particular entity" } }, "pullRequests": { "type": "array", "description": "Pull requests errors", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Entity id" }, "errorMessages": { "type": "array", "description": "Error message", "items": { "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 error happened with particular entity" } } }, "description": "Represents errors related to 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" } } }, "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": { "type": "object", "required": [ "errorMessages" ], "properties": { "errorMessages": { "type": "array", "description": "List of errors occurred.", "items": { "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 OAuth token, or token is invalid." }, "403": { "description": "The OAuth token used does not correspond to an app that defines the `development information` permission." }, "413": { "description": "Data is too large. Submit fewer devinfo entities in each payload.", "content": { "application/json": { "schema": { "type": "object", "required": [ "errorMessages" ], "properties": { "errorMessages": { "type": "array", "description": "List of errors occurred.", "items": { "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." }, "500": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "type": "object", "required": [ "errorMessages" ], "properties": { "errorMessages": { "type": "array", "description": "List of errors occurred.", "items": { "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." } }, "requestBody": { "content": { "application/json": { "schema": { "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": { "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" }, "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" }, "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 255 characters" }, "url": { "type": "string", "example": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example", "description": "The URL of this repository. Max length is 1024 characters" }, "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": { "type": "object", "required": [ "id", "issueKeys", "updateSequenceId", "author", "authorTimestamp", "displayId", "fileCount", "hash", "message", "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. Minimum number of issue keys is 1. Maximum number of issue keys is 100", "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", "example": "a7727ee6350c33cdf90826dc21abaa26a5704370", "description": "The hash of the commit. Max length is 255 characters" }, "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" }, "author": { "description": "The author of this commit", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Jane Doe", "description": "The name of this user in a format suitable for display. Max length is 255 characters" }, "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" }, "username": { "type": "string", "example": "jdoe", "description": "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" }, "url": { "type": "string", "example": "https://atlassian.com/account/jane_doe", "description": "The URL of the profile for this user. Max length is 1024 characters" }, "avatar": { "type": "string", "example": "https://atlassian.com/account/jane_doe/avatar/32", "description": "The URL of the avatar for this user. Max length is 1024 characters" } } }, "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 1024 characters" }, "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", "items": { "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" }, "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 1024 characters" }, "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" } }, "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 commits is 400", "items": { "type": "object", "required": [ "id", "issueKeys", "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" }, "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. Minimum number of issue keys is 1. Maximum number of issue keys is 100", "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. " }, "name": { "type": "string", "example": "master", "description": "The name of the branch. Max length is 255 characters" }, "lastCommit": { "description": "The most recent commit on this branch, used to display the date of the latest activity for this branch", "type": "object", "required": [ "id", "issueKeys", "updateSequenceId", "author", "authorTimestamp", "displayId", "fileCount", "hash", "message", "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. Minimum number of issue keys is 1. Maximum number of issue keys is 100", "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", "example": "a7727ee6350c33cdf90826dc21abaa26a5704370", "description": "The hash of the commit. Max length is 255 characters" }, "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" }, "author": { "description": "The author of this commit", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Jane Doe", "description": "The name of this user in a format suitable for display. Max length is 255 characters" }, "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" }, "username": { "type": "string", "example": "jdoe", "description": "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" }, "url": { "type": "string", "example": "https://atlassian.com/account/jane_doe", "description": "The URL of the profile for this user. Max length is 1024 characters" }, "avatar": { "type": "string", "example": "https://atlassian.com/account/jane_doe/avatar/32", "description": "The URL of the avatar for this user. Max length is 1024 characters" } } }, "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 1024 characters" }, "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", "items": { "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" }, "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 1024 characters" }, "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" } } }, "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 1024 characters" }, "url": { "type": "string", "example": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/branch/master", "description": "The URL of the branch. Max length is 1024 characters" } }, "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 commits is 400", "items": { "type": "object", "required": [ "id", "issueKeys", "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. Minimum number of issue keys is 1. Maximum number of issue keys is 100", "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. " }, "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" }, "author": { "description": "The author of this pull request", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Jane Doe", "description": "The name of this user in a format suitable for display. Max length is 255 characters" }, "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" }, "username": { "type": "string", "example": "jdoe", "description": "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" }, "url": { "type": "string", "example": "https://atlassian.com/account/jane_doe", "description": "The URL of the profile for this user. Max length is 1024 characters" }, "avatar": { "type": "string", "example": "https://atlassian.com/account/jane_doe/avatar/32", "description": "The URL of the avatar for this user. Max length is 1024 characters" } } }, "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" }, "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 255 characters" }, "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" }, "reviewers": { "type": "array", "description": "The list of reviewers of this pull request", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Jane Doe", "description": "The name of this reviewer. Max length is 255 characters" }, "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": "The URL of the profile for this reviewer. Max length is 1024 characters" }, "avatar": { "type": "string", "example": "https://atlassian.com/account/jane_doe/avatar/32", "description": "The URL of the avatar for this reviewer. Max length is 1024 characters" } }, "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 1024 characters" }, "displayId": { "type": "string", "example": "Pull request 2", "description": "Shortened identifier for this pull request, used for display. Max length is 255 characters" } }, "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 1024 characters" }, "avatarDescription": { "type": "string", "example": "Avatar description", "description": "Description of the avatar for this repository. Max length is 1024 characters" }, "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" }, "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" }, "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": { "type": "object", "description": "Details about the provider", "required": [ "product" ], "properties": { "product": { "type": "string", "example": "Bitbucket Cloud", "description": "The product sending data" } } } }, "description": "Request object for development information push operations, entities are grouped by repository" } } }, "description": "Request object, which contains development information", "required": true } } }, "/jira/devinfo/0.1/cloud/{cloudId}/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": "cloudId", "in": "path", "description": "The cloud ID of the site.", "required": true, "schema": { "type": "string" } }, { "name": "repositoryId", "in": "path", "description": "The ID of repository to fetch", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The repository data currently stored for the given ID.", "content": { "application/json": { "schema": { "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" }, "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" }, "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 255 characters" }, "url": { "type": "string", "example": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example", "description": "The URL of this repository. Max length is 1024 characters" }, "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": { "type": "object", "required": [ "id", "issueKeys", "updateSequenceId", "author", "authorTimestamp", "displayId", "fileCount", "hash", "message", "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. Minimum number of issue keys is 1. Maximum number of issue keys is 100", "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", "example": "a7727ee6350c33cdf90826dc21abaa26a5704370", "description": "The hash of the commit. Max length is 255 characters" }, "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" }, "author": { "description": "The author of this commit", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Jane Doe", "description": "The name of this user in a format suitable for display. Max length is 255 characters" }, "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" }, "username": { "type": "string", "example": "jdoe", "description": "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" }, "url": { "type": "string", "example": "https://atlassian.com/account/jane_doe", "description": "The URL of the profile for this user. Max length is 1024 characters" }, "avatar": { "type": "string", "example": "https://atlassian.com/account/jane_doe/avatar/32", "description": "The URL of the avatar for this user. Max length is 1024 characters" } } }, "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 1024 characters" }, "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", "items": { "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" }, "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 1024 characters" }, "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" } }, "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 commits is 400", "items": { "type": "object", "required": [ "id", "issueKeys", "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" }, "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. Minimum number of issue keys is 1. Maximum number of issue keys is 100", "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. " }, "name": { "type": "string", "example": "master", "description": "The name of the branch. Max length is 255 characters" }, "lastCommit": { "description": "The most recent commit on this branch, used to display the date of the latest activity for this branch", "type": "object", "required": [ "id", "issueKeys", "updateSequenceId", "author", "authorTimestamp", "displayId", "fileCount", "hash", "message", "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. Minimum number of issue keys is 1. Maximum number of issue keys is 100", "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", "example": "a7727ee6350c33cdf90826dc21abaa26a5704370", "description": "The hash of the commit. Max length is 255 characters" }, "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" }, "author": { "description": "The author of this commit", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Jane Doe", "description": "The name of this user in a format suitable for display. Max length is 255 characters" }, "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" }, "username": { "type": "string", "example": "jdoe", "description": "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" }, "url": { "type": "string", "example": "https://atlassian.com/account/jane_doe", "description": "The URL of the profile for this user. Max length is 1024 characters" }, "avatar": { "type": "string", "example": "https://atlassian.com/account/jane_doe/avatar/32", "description": "The URL of the avatar for this user. Max length is 1024 characters" } } }, "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 1024 characters" }, "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", "items": { "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" }, "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 1024 characters" }, "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" } } }, "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 1024 characters" }, "url": { "type": "string", "example": "https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example/branch/master", "description": "The URL of the branch. Max length is 1024 characters" } }, "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 commits is 400", "items": { "type": "object", "required": [ "id", "issueKeys", "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. Minimum number of issue keys is 1. Maximum number of issue keys is 100", "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. " }, "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" }, "author": { "description": "The author of this pull request", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Jane Doe", "description": "The name of this user in a format suitable for display. Max length is 255 characters" }, "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" }, "username": { "type": "string", "example": "jdoe", "description": "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" }, "url": { "type": "string", "example": "https://atlassian.com/account/jane_doe", "description": "The URL of the profile for this user. Max length is 1024 characters" }, "avatar": { "type": "string", "example": "https://atlassian.com/account/jane_doe/avatar/32", "description": "The URL of the avatar for this user. Max length is 1024 characters" } } }, "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" }, "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 255 characters" }, "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" }, "reviewers": { "type": "array", "description": "The list of reviewers of this pull request", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Jane Doe", "description": "The name of this reviewer. Max length is 255 characters" }, "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": "The URL of the profile for this reviewer. Max length is 1024 characters" }, "avatar": { "type": "string", "example": "https://atlassian.com/account/jane_doe/avatar/32", "description": "The URL of the avatar for this reviewer. Max length is 1024 characters" } }, "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 1024 characters" }, "displayId": { "type": "string", "example": "Pull request 2", "description": "Shortened identifier for this pull request, used for display. Max length is 255 characters" } }, "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 1024 characters" }, "avatarDescription": { "type": "string", "example": "Avatar description", "description": "Description of the avatar for this repository. Max length is 1024 characters" }, "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" }, "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 OAuth token, or token is invalid." }, "403": { "description": "The OAuth token used does not correspond to an app that defines the `development information` permission." }, "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": { "type": "object", "required": [ "errorMessages" ], "properties": { "errorMessages": { "type": "array", "description": "List of errors occurred.", "items": { "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." } } }, "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": "cloudId", "in": "path", "description": "The cloud ID of the site.", "required": true, "schema": { "type": "string" } }, { "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" } } ], "responses": { "202": { "description": "Delete request has been accepted. Data will eventually be removed from Jira if it exists." }, "401": { "description": "Missing a OAuth token, or token is invalid." }, "403": { "description": "The OAuth token used does not correspond to an app that defines the `development information` permission." }, "429": { "description": "API rate limit has been exceeded." }, "500": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "type": "object", "required": [ "errorMessages" ], "properties": { "errorMessages": { "type": "array", "description": "List of errors occurred.", "items": { "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." } } } }, "/jira/devinfo/0.1/cloud/{cloudId}/bulkByProperties": { "delete": { "tags": [ "Development Information" ], "summary": "Delete development information by properties", "description": "Deletes development information entities which have all the provided properties. Entities will be deleted that match ALL of the properties (i.e. treated as an AND). For example if request is DELETE bulk?accountId=123&projectId=ABC entities which have properties accountId=123 and projectId=ABC will be deleted. Special property '\\_updateSequenceId' can be used to delete 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 delete by. Deletion is performed asynchronously: specified entities will eventually be removed from Jira.", "operationId": "deleteByProperties", "parameters": [ { "name": "cloudId", "in": "path", "description": "The cloud ID of the site.", "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": { "type": "object", "required": [ "errorMessages" ], "properties": { "errorMessages": { "type": "array", "description": "List of errors occurred.", "items": { "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 OAuth token, or token is invalid." }, "403": { "description": "The OAuth token used does not correspond to an app that defines the `development information` permission." }, "429": { "description": "API rate limit has been exceeded." }, "500": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "type": "object", "required": [ "errorMessages" ], "properties": { "errorMessages": { "type": "array", "description": "List of errors occurred.", "items": { "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." } } } }, "/jira/devinfo/0.1/cloud/{cloudId}/existsByProperties": { "get": { "tags": [ "Development Information" ], "summary": "Check if data exists for the supplied properties", "description": "Checks if development information 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 entity or 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": "cloudId", "in": "path", "description": "The cloud ID of the site.", "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": { "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": { "type": "object", "required": [ "errorMessages" ], "properties": { "errorMessages": { "type": "array", "description": "List of errors occurred.", "items": { "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 OAuth token, or token is invalid." }, "403": { "description": "The OAuth token used does not correspond to an app that defines the `development information` permission." }, "429": { "description": "API rate limit has been exceeded." }, "500": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "type": "object", "required": [ "errorMessages" ], "properties": { "errorMessages": { "type": "array", "description": "List of errors occurred.", "items": { "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." } } } }, "/jira/devinfo/0.1/cloud/{cloudId}/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": "cloudId", "in": "path", "description": "The cloud ID of the site.", "required": true, "schema": { "type": "string" } }, { "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" } } ], "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": { "type": "object", "required": [ "errorMessages" ], "properties": { "errorMessages": { "type": "array", "description": "List of errors occurred.", "items": { "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 OAuth token, or token is invalid." }, "403": { "description": "The OAuth token used does not correspond to an app that defines the `development information` permission." }, "429": { "description": "API rate limit has been exceeded." }, "500": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "type": "object", "required": [ "errorMessages" ], "properties": { "errorMessages": { "type": "array", "description": "List of errors occurred.", "items": { "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." } } } }, "/rest/deployments/0.1/bulk": { "post": { "operationId": "submitDeployments", "summary": "Submit deployment data", "tags": [ "Deployments" ], "description": "Update / insert deployment data.\n\nDeployments are identified by the combination of `pipelineId`, `environmentId` and `deploymentSequenceNumber`, and existing deployment data for the same deployment will be replaced if it exists and the `updateSequenceNumber` of existing data is less than the incoming data.\n\nSubmissions are processed asynchronously. Submitted data will eventually be available in Jira. Most updates are available within a short period of time, but may take some time during peak load and/or maintenance times. The `getDeploymentByKey` operation can be used to confirm that data has been stored successfully (if needed).\n\nIn the case of multiple deployments being submitted in one request, each is validated individually prior to submission. Details of which deployments failed submission (if any) are available in the response object.\n\nOnly on-premise integrations apps that define the `deployment` permission can access this resource.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitDeploymentRequest" } } }, "description": "Deployment data to submit.\n", "required": true }, "responses": { "202": { "description": "Submission accepted. Each submitted deployment that is of a valid format will eventually be available in Jira.\n\nDetails of which deployments were submitted and which failed submission (due to data format problems etc.) are available in the response object.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitDeploymentsResponse" } } } }, "400": { "description": "Request has incorrect format.\n\nNote that in the case of an individual deployment having an invalid format (rather than the request as a whole) the response for the request will be a 202 and details of the invalid deployment will be contained in the response object.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } }, "401": { "description": "Missing a OAuth token, or token is invalid.\n" }, "403": { "description": "The OAuth token used does not correspond to an app that defines the `deployment information` permission." }, "413": { "description": "Data is too large. Submit fewer deployments in each payload.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } }, "429": { "description": "API rate limit has been exceeded.\n" }, "503": { "description": "Service is unavailable due to maintenance or other reasons.\n" }, "default": { "description": "An unknown error has occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } } } } }, "/rest/deployments/0.1/bulkByProperties": { "delete": { "operationId": "deleteDeploymentsByProperty", "summary": "Delete deployments by Property", "tags": [ "Deployments" ], "description": "Bulk delete all deployments that match the given request.\n\nIn addition to the optional `_updateSequenceNumber`, one or more query params must be supplied to specify the Properties to delete by.\nIf more than one Property is provided, data will be deleted that matches ALL of the Properties (i.e. treated as AND).\nSee the documentation for the `submitDeployments` operation for more details.\n\nExample operation: DELETE /bulkByProperties?accountId=account-123&createdBy=user-456\n\nDeletion is performed asynchronously. The `getDeploymentByKey` operation can be used to confirm that data has been deleted successfully (if needed).\n\nOnly on-premise integrations apps that define the `deployment` permission can access this resource.", "parameters": [ { "name": "_updateSequenceNumber", "in": "query", "description": "An optional `updateSequenceNumber` to use to control deletion.\n\nOnly stored data with an `updateSequenceNumber` less than or equal to that provided will be deleted.\nThis can be used help ensure submit/delete requests are applied correctly if issued close together.\n\nIf not provided, all stored data that matches the request will be deleted.\n", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "202": { "description": "Delete accepted. Data will eventually be removed from Jira.\n" }, "400": { "description": "Request has incorrect format (e.g. missing at least one Property param).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } }, "401": { "description": "Missing a OAuth token, or token is invalid.\n" }, "403": { "description": "The OAuth token used does not correspond to an app that defines the `deployment information` permission." }, "429": { "description": "API rate limit has been exceeded.\n" }, "503": { "description": "Service is unavailable due to maintenance or other reasons.\n" }, "default": { "description": "An unknown error has occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } } } } }, "/rest/deployments/0.1/pipelines/{pipelineId}/environments/{environmentId}/deployments/{deploymentSequenceNumber}": { "get": { "operationId": "getDeploymentByKey", "summary": "Get a deployment by key", "tags": [ "Deployments" ], "description": "Retrieve the currently stored deployment data for the given `pipelineId`, `environmentId` and `deploymentSequenceNumber` combination.\n\nThe result will be what is currently stored, ignoring any pending updates or deletes.\n\nOnly on-premise integrations apps that define the `deployment` permission can access this resource.", "parameters": [ { "name": "pipelineId", "in": "path", "description": "The ID of the deployment's pipeline.\n", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "environmentId", "in": "path", "description": "The ID of the deployment's environment.\n", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "deploymentSequenceNumber", "in": "path", "description": "The deployment's deploymentSequenceNumber.\n", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "The deployment data currently stored for the given ID.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentData" } } } }, "401": { "description": "Missing a OAuth token, or token is invalid.\n" }, "403": { "description": "The OAuth token used does not correspond to an app that defines the `deployment information` permission." }, "404": { "description": "No data found for the given deployment ID.\n" }, "429": { "description": "API rate limit has been exceeded.\n" }, "503": { "description": "Service is unavailable due to maintenance or other reasons.\n" }, "default": { "description": "An unknown error has occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } } } }, "delete": { "operationId": "deleteDeploymentByKey", "summary": "Delete a deployment by key", "tags": [ "Deployments" ], "description": "Delete the currently stored deployment data for the given `pipelineId`, `environmentId` and `deploymentSequenceNumber` combination.\n\nDeletion is performed asynchronously. The `getDeploymentByKey` operation can be used to confirm that data has been deleted successfully (if needed).\n\nOnly on-premise integrations apps that define the `deployment` permission can access this resource.", "parameters": [ { "name": "pipelineId", "in": "path", "description": "The ID of the deployment's pipeline.\n", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "environmentId", "in": "path", "description": "The ID of the deployment's environment.\n", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "deploymentSequenceNumber", "in": "path", "description": "The deployment's deploymentSequenceNumber.\n", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "_updateSequenceNumber", "in": "query", "description": "An optional `_updateSequenceNumber` to use to control deletion.\n\nOnly stored data with an `updateSequenceNumber` less than or equal to that provided will be deleted.\nThis can be used help ensure submit/delete requests are applied correctly if issued close together.\n", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "202": { "description": "Delete has been accepted. Data will eventually be removed from Jira if it exists.\n" }, "401": { "description": "Missing a OAuth token, or token is invalid.\n" }, "403": { "description": "The OAuth token used does not correspond to an app that defines the `deployment information` permission." }, "429": { "description": "API rate limit has been exceeded.\n" }, "503": { "description": "Service is unavailable due to maintenance or other reasons.\n" }, "default": { "description": "An unknown error has occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } } } } } }, "servers": [ { "url": "//api.atlassian.com/" } ], "components": { "requestBodies": { }, "schemas": { "ErrorMessages": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ErrorMessage" } }, "ErrorMessage": { "description": "A message supplied in the case of an error.", "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." } } }, "SubmitBuildsResponse": { "description": "The result of a successful `submitBuilds` request.\n", "type": "object", "properties": { "acceptedBuilds": { "description": "The keys of builds that have been accepted for submission. A build key is a composite key that consists of\n`pipelineId` and `buildNumber`.\n\nA build may be rejected if it was only associated with unknown issue keys, or if the submitted data for that\nbuild does not match the required schema.\n\nNote that a build that isn't updated due to it's `updateSequenceNumber` being out of order is not\nconsidered a failed submission.\n", "type": "array", "items": { "$ref": "#/components/schemas/BuildKey" } }, "rejectedBuilds": { "description": "Details of builds that have not been accepted for submission.\n\nA build may be rejected if it was only associated with unknown issue keys, or if the submitted data for the\nbuild does not match the required schema.\n", "type": "array", "items": { "$ref": "#/components/schemas/RejectedBuild" } }, "unknownIssueKeys": { "description": "Issue keys that are not known on this Jira instance (if any).\n\nThese may be invalid keys (e.g. `UTF-8` is sometimes incorrectly identified as a Jira issue key), or they\nmay be for projects that no longer exist.\n\nIf a build has been associated with issue keys other than those in this array it will still be stored against\nthose valid keys. If a build was only associated with issue keys deemed to be invalid it won't be persisted.\n", "type": "array", "items": { "$ref": "#/components/schemas/IssueKey" } } } }, "SubmitBuildsRequest": { "description": "The payload used to submit (update / insert) build data.", "type": "object", "required": [ "builds" ], "properties": { "properties": { "$ref": "#/components/schemas/Properties" }, "builds": { "description": "A list of builds to submit to Jira.\n\nEach build may be associated with one or more Jira issue keys, and will be associated with any properties\nincluded in this request.\n", "type": "array", "items": { "$ref": "#/components/schemas/BuildData" }, "minItems": 1 } } }, "BuildData": { "description": "Data related to a single build\n", "required": [ "pipelineId", "buildNumber", "displayName", "url", "state", "lastUpdated", "updateSequenceNumber", "issueKeys" ], "properties": { "schemaVersion": { "description": "The schema version used for this data.\n\nPlaceholder to support potential schema changes in the future.\n", "type": "string", "enum": [ "1.0" ], "default": "1.0", "example": "1.0" }, "pipelineId": { "description": "An ID that relates a sequence of builds. Depending on your use case this might be a project ID, pipeline ID,\nplan key etc. - whatever logical unit you use to group a sequence of builds.\n\nThe combination of `pipelineId` and `buildNumber` must uniquely identify a build you have provided.\n", "type": "string", "maxLength": 255, "example": "my-build-plan" }, "buildNumber": { "description": "Identifies a build within the sequence of builds identified by the build `pipelineId`.\n\nUsed to identify the 'most recent' build in that sequence of builds.\n\nThe combination of `pipelineId` and `buildNumber` must uniquely identify a build you have provided.\n", "type": "integer", "format": "int64", "example": 16 }, "updateSequenceNumber": { "description": "A nubmer used to apply an order to the updates to the build, as identified by `pipelineId` and `buildNumber`,\nin the case of out-of-order receipt of update requests.\n\nIt must be a monotonically increasing number. For example, epoch time could be one way to generate the\n`updateSequenceNumber`.\n\nUpdates for a build that is received with an `updateSqeuenceNumber` less than or equal to what is currently\nstored will be ignored.\n", "type": "integer", "format": "int64", "example": 1523494301448 }, "displayName": { "description": "The human-readable name for the build.\n\nWill be shown in the UI.\n", "type": "string", "maxLength": 255, "example": "My Project build #16" }, "description": { "description": "An optional description to attach to this build.\n\nThis may be anything that makes sense in your system.\n", "type": "string", "maxLength": 255, "example": "My Project build #16: Failed" }, "label": { "description": "A human-readable string that to provide information about the build.\n", "type": "string", "maxLength": 255 }, "url": { "description": "The URL to this build in your system.\n", "type": "string", "format": "URL" }, "state": { "$ref": "#/components/schemas/BuildState" }, "lastUpdated": { "description": "The last-updated timestamp to present to the user as a summary of the state of the build.\n", "type": "string", "format": "date-time", "example": "2018-01-20T23:27:25+00:00" }, "issueKeys": { "description": "The Jira issue keys to associate the build information with.\n\nYou are free to associate issue keys in any way you like. However, we recommend that you use the name\nof the branch the build was executed on, and extract issue keys from that name using a simple regex. This has\nthe advantage that it provides an intuitive association of builds to issue keys.\n", "type": "array", "items": { "$ref": "#/components/schemas/IssueKey" }, "minItems": 1, "maxItems": 100 }, "testInfo": { "$ref": "#/components/schemas/TestInfo" }, "references": { "description": "Optional information that links a build to a commit, branch etc.\n", "type": "array", "items": { "$ref": "#/components/schemas/BuildReferences" }, "minItems": 1, "maxItems": 5 } } }, "BuildKey": { "description": "Fields that uniquely reference a build.\n", "required": [ "pipelineId", "buildNumber" ], "type": "object", "properties": { "pipelineId": { "description": "An ID that relates a sequence of builds. Depending on your system this might be a project ID, pipeline ID,\nplan key etc. - whatever logical unit you use to group a sequence of builds.\n\nThe combination of `pipelineId` and `buildNumber` must uniquely identify the build.\n", "type": "string", "maxLength": 255, "example": "my-build-plan" }, "buildNumber": { "description": "Identifies a build within the sequence of builds identified by the build `pipelineId`.\n\nUsed to identify the 'most recent' build in that sequence of builds.\n\nThe combination of `pipelineId` and `buildNumber` must uniquely identify the build.\n", "type": "integer", "format": "int64", "example": 16 } } }, "BuildState": { "description": "The state of a build.\n\n* `pending` - The build is queued, or some manual action is required.\n* `in_progress` - The build is currently running.\n* `successful` - The build completed successfully.\n* `failed` - The build failed.\n* `cancelled` - The build has been cancelled or stopped.\n* `unknown` - The build is in an unknown state.\n", "type": "string", "enum": [ "pending", "in_progress", "successful", "failed", "cancelled", "unknown" ], "example": "failed" }, "TestInfo": { "description": "Information about tests that were executed during a build.\n", "type": "object", "required": [ "totalNumber", "numberPassed", "numberFailed" ], "properties": { "totalNumber": { "description": "The total number of tests considered during a build.\n", "type": "integer", "format": "int64", "example": 150 }, "numberPassed": { "description": "The number of tests that passed during a build.\n", "type": "integer", "format": "int64", "example": 145 }, "numberFailed": { "description": "The number of tests that failed during a build.\n", "type": "integer", "format": "int64", "example": 5 }, "numberSkipped": { "description": "The number of tests that were skipped during a build.\n", "type": "integer", "format": "int64", "default": 0, "example": 0 } } }, "BuildReferences": { "description": "Information that links a build to a commit, branch etc.\n\nUsed to provide a richer user experience by enabling us to associate builds from your system with e.g.\nbranches / commits / tags etc. supplied by another app in the Jira UI.\n", "type": "object", "properties": { "commit": { "$ref": "#/components/schemas/BuildCommitReference" }, "ref": { "$ref": "#/components/schemas/BuildRefReference" } } }, "BuildCommitReference": { "description": "Details about the commit the build was run against.\n", "type": "object", "required": [ "id", "repositoryUri" ], "properties": { "id": { "description": "The ID of the commit. E.g. for a Git repository this would be the SHA1 hash.\n", "type": "string", "maxLength": 255, "example": "08cd9c26b2b8d7cf6e6af6b49da8895d065c259f" }, "repositoryUri": { "description": "An identifier for the repository containing the commit.\n\nIn most cases this should be the URL of the repository in the SCM provider.\n\nFor cases where the build was executed against a local repository etc. this should be some identifier that is\nunique to that repository.\n", "type": "string", "maxLength": 255, "example": "https://bitbucket.org/atlassian/biij-vendor-api" } } }, "BuildRefReference": { "description": "Details about the ref the build was run on.\n", "type": "object", "required": [ "name", "uri" ], "properties": { "name": { "description": "The name of the ref the build ran on\n", "type": "string", "maxLength": 255, "example": "feature/ISSUE-123-some-work" }, "uri": { "description": "An identifer for the ref.\n\nIn most cases this should be the URL of the tag/branch etc. in the SCM provider.\n\nFor cases where the build was executed against a local repository etc. this should be something that uniquely\nidentifies the ref.\n", "type": "string", "maxLength": 255, "example": "https://bitbucket.org/atlassian/biij-vendor-api/refs/feature/ISSUE-123-some-work" } } }, "Properties": { "description": "Properties assigned to build data that can then be used for delete / query operations.\n\nExamples might be an account or user ID that can then be used to clean up data if an account is removed from\nthe Provider system.\n\nProperties are supplied as key/value pairs, a maximum of 5 properties can be supplied, and keys must not\ncontain ':' or start with '_'.\n", "type": "object", "additionalProperties": { "type": "string", "maxLength": 255 }, "maxProperties": 5, "example": { "accountId": "account-234", "projectId": "project-123" } }, "IssueKey": { "description": "An issue key that references an issue in Jira.\n", "type": "string", "pattern": "\\w{1,255}-\\d{1,255}", "example": "ISSUE-123" }, "RejectedBuild": { "description": "A build that has not been accepted for submission, usually due to a problem with the request data.\n\nThe object is comprised of the key of the rejected build and the corresponding error messages.\n", "type": "object", "required": [ "key", "errors" ], "properties": { "key": { "$ref": "#/components/schemas/BuildKey" }, "errors": { "description": "The error messages for the rejected build", "type": "array", "items": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "SubmitDeploymentsResponse": { "description": "The result of a successful submitDeployments request.\n", "properties": { "acceptedDeployments": { "description": "The keys of deployments that have been accepted for submission. A deployment key is a composite key that consists of `pipelineId`, `environmentId` and `deploymentSequenceNumber`.\n\nA deployment may be rejected if it was only associated with unknown issue keys.\n\nNote that a deployment that isn't updated due to it's updateSequenceNumber being out of order is not considered a failed submission.\n", "type": "array", "items": { "$ref": "#/components/schemas/DeploymentKey" } }, "rejectedDeployments": { "description": "Details of deployments that have not been accepted for submission, usually due to a problem with the request data.\n\nThe object will contain the deployment key and any errors associated with that deployment that have prevented it being submitted.\n", "type": "array", "items": { "$ref": "#/components/schemas/RejectedDeployment" } }, "unknownIssueKeys": { "description": "Issue keys that are not known on this Jira instance (if any).\n\nThese 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.\n\nIf a deployment has been associated with issue keys other than those in this array it will still be stored against those valid keys.\nIf a deployment was only associated with issue keys deemed to be invalid it won't be persisted.\n", "type": "array", "items": { "$ref": "#/components/schemas/IssueKey" } } } }, "SubmitDeploymentRequest": { "description": "The payload used to submit (update / insert) deployment data.", "required": [ "deployments" ], "properties": { "properties": { "$ref": "#/components/schemas/Properties" }, "deployments": { "description": "A list of deployments to submit to Jira.\n\nEach deployment may be associated with one or more Jira issue keys, and will be associated with any properties included in this request.\n", "type": "array", "items": { "$ref": "#/components/schemas/DeploymentData" }, "minItems": 1 } } }, "DeploymentData": { "description": "Data related to a specific deployment in a specific environment that the deployment is present in.\n", "required": [ "deploymentSequenceNumber", "updateSequenceNumber", "displayName", "issueKeys", "url", "description", "lastUpdated", "state", "pipeline", "environment" ], "properties": { "deploymentSequenceNumber": { "description": "This is the identifier for the deployment. It must be unique for the specified pipeline and environment. It must be a monotonically increasing number, as this is used to sequence the deployments.\n", "type": "integer", "format": "int64", "example": 100 }, "updateSequenceNumber": { "description": "A number used to apply an order to the updates to the deployment, as identified by the deploymentSequenceNumber, in the case of out-of-order receipt of update requests. It must be a monotonically increasing number. For example, epoch time could be one way to generate the updateSequenceNumber.\n", "type": "integer", "format": "int64", "example": 1 }, "issueKeys": { "description": "The Jira issue keys to associate the deployment information with.\n", "type": "array", "items": { "$ref": "#/components/schemas/IssueKey" }, "minItems": 1, "maxItems": 100 }, "displayName": { "description": "The human-readable name for the deployment. Will be shown in the UI.\n", "type": "string", "maxLength": 255, "example": "Deployment number 16 of Data Depot" }, "url": { "description": "A URL users can use to link to this deployment, in this environment.\n", "type": "string", "format": "uri", "maxLength": 2000, "example": "http://mydeployer.com/project1/1111-222-333/prod-east" }, "description": { "description": "A short description of the deployment\n", "type": "string", "maxLength": 255, "example": "The bits are being transferred" }, "lastUpdated": { "description": "The last-updated timestamp to present to the user as a summary of the state of the deployment.\n", "type": "string", "format": "date-time", "example": "2018-01-20T23:27:25+00:00" }, "label": { "description": "An (optional) additional label that may be displayed with deployment information. Can be used to display version information etc. for the deployment.\n", "type": "string", "maxLength": 255, "example": "Release 2018-01-20_08-47-bc2421a" }, "state": { "description": "The state of the deployment\n", "type": "string", "enum": [ "unknown", "pending", "in_progress", "cancelled", "failed", "rolled_back", "successful" ], "example": "in_progress" }, "pipeline": { "$ref": "#/components/schemas/Pipeline" }, "environment": { "$ref": "#/components/schemas/Environment" }, "schemaVersion": { "description": "The DeploymentData schema version used for this deployment data.\n\nPlaceholder to support potential schema changes in the future.\n", "type": "string", "enum": [ "1.0" ], "default": "1.0", "example": "1.0" } } }, "Pipeline": { "description": "This object models the Continuous Delivery (CD) Pipeline concept, an automated process (usually comprised of multiple stages)\nfor getting software from version control right through to the production environment.\n", "required": [ "id", "displayName", "url" ], "properties": { "id": { "description": "The identifier of this pipeline, must be unique for the provider.\n", "type": "string", "maxLength": 255, "example": "e9c906a7-451f-4fa6-ae1a-c389e2e2d87c" }, "displayName": { "description": "The name of the pipeline to present to the user.\n", "type": "string", "maxLength": 255, "example": "Data Depot Deployment" }, "url": { "description": "A URL users can use to link to this deployment pipeline.\n", "type": "string", "format": "uri", "maxLength": 2000, "example": "http://mydeployer.com/project1" } } }, "Environment": { "description": "The environment that the deployment is present in.\n", "required": [ "id", "displayName", "type" ], "properties": { "id": { "description": "The identifier of this environment, must be unique for the provider so that it can be shared across pipelines.\n", "type": "string", "maxLength": 255, "example": "8ec94d72-a4fc-4ac0-b31d-c5a595f373ba" }, "displayName": { "description": "The name of the environment to present to the user.\n", "type": "string", "maxLength": 255, "example": "US East" }, "type": { "description": "The type of the environment.\n", "type": "string", "enum": [ "unmapped", "development", "testing", "staging", "production" ], "example": "production" } } }, "DeploymentKey": { "description": "Fields that uniquely reference a deployment.\n", "required": [ "pipelineId", "environmentId", "deploymentSequenceNumber" ], "properties": { "pipelineId": { "description": "The identifier of a pipeline, must be unique for the provider.\n", "type": "string", "maxLength": 255, "example": "e9c906a7-451f-4fa6-ae1a-c389e2e2d87c" }, "environmentId": { "description": "The identifier of an environment, must be unique for the provider so that it can be shared across pipelines.\n", "type": "string", "maxLength": 255, "example": "8ec94d72-a4fc-4ac0-b31d-c5a595f373ba" }, "deploymentSequenceNumber": { "description": "This is the identifier for the deployment. It must be unique for the specified pipeline and environment. It must be a monotonically increasing number, as this is used to sequence the deployments.\n", "type": "integer", "format": "int64", "example": 100 } } }, "RejectedDeployment": { "description": "A deployment that has not been accepted for submission, usually due to a problem with the request data.\n\nThe object is comprised of the key of the rejected deployment and the corresponding error messages.\n", "required": [ "key", "errors" ], "properties": { "key": { "$ref": "#/components/schemas/DeploymentKey" }, "errors": { "description": "The error messages for the rejected deployment", "type": "array", "items": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "securitySchemes": { "atlassianCloudOauth": { "type": "oauth2", "description": "You need to use OAuth to access this API.", "flows": { "authorizationCode": { "authorizationUrl": "https://api.atlassian.com/OAuth/authorize", "tokenUrl": "https://api.atlassian.com/OAuth/token", "scopes": {} } } } } }, "security": [ { "atlassianCloudOauth": [] } ] }