{ "openapi": "3.0.0", "info": { "description": "Jira Software Cloud REST API documentation", "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" } }, "tags": [ { "name": "Backlog", "description": "Apis related to the backlog" }, { "name": "Board", "description": "Apis related to boards" }, { "name": "Epic", "description": "Apis related to epics" }, { "name": "Issue", "description": "Apis related to issues" }, { "name": "Sprint", "description": "Apis related to sprints" }, { "name": "Development Information", "description": "Apis related to integrating development information (commits, branches and pull requests) with Jira. These apis are only available to Atlassian Connect apps. To use these apis you must have the Development Tool module (see https://developer.atlassian.com/cloud/jira/software/modules/development-tool/) in your app's descriptor" }, { "name": "Feature Flags", "description": "Apis related to integrating Feature Flags with Jira Software. These apis are only available to Atlassian Connect apps. To use these apis you must have the Feature Flag module (see https://developer.atlassian.com/cloud/jira/software/modules/feature-flag/) in your app's descriptor" }, { "name": "Deployments", "description": "Apis related to integrating deployments with Jira Software. These apis are only available to Atlassian Connect apps. To use these apis you must have the Deployment module (see https://developer.atlassian.com/cloud/jira/software/modules/deployment/) in your app's descriptor." }, { "name": "Builds", "description": "APIs related to integrating builds data with Jira Software. These apis are only available to Atlassian Connect apps. To use these apis you must have the Build module (see https://developer.atlassian.com/cloud/jira/software/modules/build/) in your app's descriptor." } ], "paths": { "/agile/1.0/backlog/issue": { "post": { "tags": [ "Backlog" ], "summary": "Move issues to backlog", "description": "Move issues to the backlog. \nThis operation is equivalent to remove future and active sprints from a given set of issues. At most 50 issues may be moved at once.", "operationId": "com.atlassian.greenhopper.api.rest.BacklogResource.moveIssuesToBacklog_post", "responses": { "204": { "description": "Empty response is returned if operation was successful." }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if user does not a have valid license or does not have permission to assign issues." }, "404": { "description": "Returned if sprint does not exist or the user cannot view it." } }, "deprecated": false, "requestBody": { "$ref": "#/components/requestBodies/com.atlassian.greenhopper.api.rest.BacklogResource.moveIssuesToBacklog_postIssueassignrequestbean" }, "x-atlassian-connect-scope": "WRITE" } }, "/agile/1.0/backlog/{boardId}/issue": { "post": { "tags": [ "Backlog" ], "summary": "Move issues to backlog for board", "description": "Move issues to the backlog of a particular board (if they are already on that board). \nThis operation is equivalent to remove future and active sprints from a given set of issues if the board has sprints If the board does not have sprints this will put the issues back into the backlog from the board. At most 50 issues may be moved at once.", "operationId": "com.atlassian.greenhopper.api.rest.BacklogResource.moveIssuesToBacklogForBoard_post", "parameters": [ { "name": "boardId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Empty response is returned if operation was successful." }, "207": { "description": "Returns the list of issue with status of rank operation.", "content": { "application/json": { "examples": { "response": { "value": "{\"entries\":[{\"issueId\":10000,\"issueKey\":\"PR-1\",\"status\":200},{\"issueId\":10001,\"issueKey\":\"PR-2\",\"status\":200},{\"issueId\":10002,\"issueKey\":\"PR-3\",\"status\":503,\"errors\":[\"JIRA Agile cannot execute the rank operation at this time. Please try again later.\"]}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if user does not a have valid license or does not have permission to assign issues." }, "404": { "description": "Returned if sprint does not exist or the user cannot view it." } }, "deprecated": false, "requestBody": { "$ref": "#/components/requestBodies/com.atlassian.greenhopper.api.rest.BacklogResource.moveIssuesToBacklogForBoard_postIssuerankrequestbean" }, "x-atlassian-connect-scope": "WRITE" } }, "/agile/1.0/board": { "get": { "tags": [ "Board" ], "summary": "Get all boards", "description": "Returns all boards. This only includes boards that the user has permission to view.", "operationId": "com.atlassian.greenhopper.api.rest.BoardResource.getAllBoards_get", "parameters": [ { "name": "startAt", "in": "query", "description": "The starting index of the returned boards. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of boards to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "type", "in": "query", "description": "Filters results to boards of the specified types. Valid values: scrum, kanban, simple.", "required": false, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Filters results to boards that match or partially match the specified name.", "required": false, "schema": { "type": "string" } }, { "name": "projectKeyOrId", "in": "query", "description": "Filters results to boards that are relevant to a project. Relevance means that the jql filter defined in board contains a reference to a project.", "required": false, "schema": { "type": "string" } }, { "name": "accountIdLocation", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "userkeyLocation", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "usernameLocation", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "projectLocation", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "includePrivate", "in": "query", "description": "Appends private boards to the end of the list. The name and type fields are excluded for security reasons.", "required": false, "schema": { "type": "boolean" } }, { "name": "negateLocationFiltering", "in": "query", "description": "If set to true, negate filters used for querying by location. By default false.", "required": false, "schema": { "type": "boolean" } }, { "name": "orderBy", "in": "query", "description": "Ordering of the results by a given field. If not provided, values will not be sorted. Valid values: name.", "required": false, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "description": "List of fields to expand for each board. Valid values: admins, permissions.", "required": false, "schema": { "type": "string" } }, { "name": "filterId", "in": "query", "description": "Filters results to boards that are relevant to a filter. Not supported for next-gen boards.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Returns the requested boards, at the specified page of the results.", "content": { "application/json": { "examples": { "response": { "value": "{\"maxResults\":2,\"startAt\":1,\"total\":5,\"isLast\":false,\"values\":[{\"id\":84,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/84\",\"name\":\"scrum board\",\"type\":\"scrum\"},{\"id\":92,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/92\",\"name\":\"kanban board\",\"type\":\"kanban\"}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not have valid license." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" }, "post": { "tags": [ "Board" ], "summary": "Create board", "description": "Creates a new board. Board name, type and filter ID is required.\n\n* `name` \\- Must be less than 255 characters.\n* `type` \\- Valid values: scrum, kanban\n* `filterId` \\- ID of a filter that the user has permissions to view. Note, if the user does not have the 'Create shared objects' permission and tries to create a shared board, a private board will be created instead (remember that board sharing depends on the filter sharing).\n* `location` \\- The container that the board will be located in. `location` must include the `type` property (Valid values: project, user). If choosing 'project', then a project must be specified by a `projectKeyOrId` property in `location`. If choosing 'user', the current user is chosen by default. The `projectKeyOrId` property should not be provided.\n\nNote:\n\n* If you want to create a new project with an associated board, use the [Jira platform REST API](https://docs.atlassian.com/jira/REST/latest). For more information, see the [Create project](#api-rest-api--project-post) method. The `projectTypeKey` for software boards must be 'software' and the `projectTemplateKey` must be either `com.pyxis.greenhopper.jira:gh-kanban-template` or `com.pyxis.greenhopper.jira:gh-scrum-template`.\n* You can create a filter using the [Jira REST API](https://docs.atlassian.com/jira/REST/latest). For more information, see the [Create filter](#api-rest-api--filter-post) method.\n* If you do not ORDER BY the Rank field for the filter of your board, you will not be able to reorder issues on the board.", "operationId": "com.atlassian.greenhopper.api.rest.BoardResource.createBoard_post", "responses": { "201": { "description": "Returns the created board.", "content": { "application/json": { "examples": { "response": { "value": "{\"id\":84,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/84\",\"name\":\"scrum board\",\"type\":\"scrum\"}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." } }, "deprecated": false, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "filterId": { "type": "integer", "format": "int64" }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "projectKeyOrId": { "type": "string" } } } } } } }, "required": true }, "x-atlassian-connect-scope": "WRITE" } }, "/agile/1.0/board/filter/{filterId}": { "get": { "tags": [ "Board" ], "summary": "Get board by filter id", "description": "Returns any boards which use the provided filter id. This method can be executed by users without a valid software license in order to find which boards are using a particular filter.", "operationId": "com.atlassian.greenhopper.api.rest.BoardResource.getBoardByFilterId_get", "parameters": [ { "name": "filterId", "in": "path", "description": "Filters results to boards that are relevant to a filter. Not supported for next-gen boards.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "startAt", "in": "query", "description": "The starting index of the returned boards. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of boards to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Returns the requested boards, at the specified page of the results.", "content": { "application/json": { "examples": { "response": { "value": "{\"id\":84,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/84\",\"name\":\"scrum board\"}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/board/{boardId}": { "get": { "tags": [ "Board" ], "summary": "Get board", "description": "Returns the board for the given board ID. This board will only be returned if the user has permission to view it. Admins without the view permission will see the board as a private one, so will see only a subset of the board's data (board location for instance).", "operationId": "com.atlassian.greenhopper.api.rest.BoardResource.getBoard_get", "parameters": [ { "name": "boardId", "in": "path", "description": "The ID of the requested board.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Returns the requested board.", "content": { "application/json": { "examples": { "response": { "value": "{\"id\":84,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/84\",\"name\":\"scrum board\",\"type\":\"scrum\",\"location\":{\"projectId\":10040,\"userId\":10040,\"userAccountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Example Project\",\"projectName\":\"Example Project\",\"projectKey\":\"Example Project Key\",\"projectTypeKey\":\"KEY\",\"name\":\"Example Project\"}}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if the board does not exist or the user does not have permission to view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" }, "delete": { "tags": [ "Board" ], "summary": "Delete board", "description": "Deletes the board. Admin without the view permission can still remove the board.", "operationId": "com.atlassian.greenhopper.api.rest.BoardResource.deleteBoard_delete", "parameters": [ { "name": "boardId", "in": "path", "description": "ID of the board to be deleted", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Returned if the board has been successfully removed." }, "403": { "description": "Returned if the user does not a have valid license, or when the user does not have the permission to delete the board. The user has to be a Jira Administrator or a board administrator to remove the board." }, "404": { "description": "Returned if a board with the given ID does not exist or the user does not have the permission to view the board." } }, "deprecated": false, "x-atlassian-connect-scope": "DELETE" } }, "/agile/1.0/board/{boardId}/backlog": { "get": { "tags": [ "Board" ], "summary": "Get issues for backlog", "description": "Returns all issues from the board's backlog, for the given board ID. This only includes issues that the user has permission to view. The backlog contains incomplete issues that are not assigned to any future or active sprint. Note, if the user does not have permission to view the board, no issues will be returned at all. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank.", "operationId": "com.atlassian.greenhopper.api.rest.BoardResource.getIssuesForBacklog_get", "parameters": [ { "name": "boardId", "in": "path", "description": "The ID of the board that has the backlog containing the requested issues.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "startAt", "in": "query", "description": "The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of issues to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details. Note, the total number of issues returned is limited by the property 'jira.search.views.default.max' in your Jira instance. If you exceed this limit, your results will be truncated.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "jql", "in": "query", "description": "Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues. \nNote that `username` and `userkey` have been deprecated as search terms for this parameter. See the [migration guide](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. Use `accountId` instead.", "required": false, "schema": { "type": "string" } }, { "name": "validateQuery", "in": "query", "description": "Specifies whether to validate the JQL query or not. Default: true.", "required": false, "schema": { "type": "boolean" } }, { "name": "fields", "in": "query", "description": "The list of fields to return for each issue. By default, all navigable and Agile fields are returned.", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "expand", "in": "query", "description": "This parameter is currently not used.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the requested issues, at the specified page of the results.", "content": { "application/json": { "examples": { "response": { "value": "{\"expand\":\"names,schema\",\"startAt\":0,\"maxResults\":50,\"total\":1,\"issues\":[{\"expand\":\"\",\"id\":\"10001\",\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001\",\"key\":\"HSP-1\",\"fields\":{\"flagged\":true,\"sprint\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/13\",\"state\":\"future\",\"name\":\"sprint 2\",\"goal\":\"sprint 2 goal\"},\"closedSprints\":[{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/23\",\"state\":\"closed\",\"name\":\"sprint 1\",\"startDate\":\"2015-04-11T15:22:00.000+10:00\",\"endDate\":\"2015-04-20T01:22:00.000+10:00\",\"completeDate\":\"2015-04-20T11:04:00.000+10:00\",\"goal\":\"sprint 1 goal\"}],\"description\":\"example bug report\",\"project\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/project/EX\",\"id\":\"10000\",\"key\":\"EX\",\"name\":\"Example\",\"avatarUrls\":{\"48x48\":\"http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000\",\"24x24\":\"http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000\",\"16x16\":\"http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000\",\"32x32\":\"http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000\"},\"projectCategory\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000\",\"id\":\"10000\",\"name\":\"FIRST\",\"description\":\"First Project Category\"},\"simplified\":false,\"style\":\"classic\"},\"comment\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000\",\"id\":\"10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"body\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.\"}]}]},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"created\":\"2019-07-22T05:46:06.698+0000\",\"updated\":\"2019-07-22T05:46:06.699+0000\",\"visibility\":{\"type\":\"role\",\"value\":\"Administrators\"}}],\"epic\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/epic/23\",\"name\":\"epic 1\",\"summary\":\"epic 1 summary\",\"color\":{\"key\":\"color_4\"},\"done\":true},\"worklog\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"comment\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"I did some work here.\"}]}]},\"updated\":\"2019-07-22T05:46:06.706+0000\",\"visibility\":{\"type\":\"group\",\"value\":\"jira-developers\"},\"started\":\"2019-07-22T05:46:06.706+0000\",\"timeSpent\":\"3h 20m\",\"timeSpentSeconds\":12000,\"id\":\"100028\",\"issueId\":\"10002\"}],\"updated\":1,\"timetracking\":{\"originalEstimate\":\"10m\",\"remainingEstimate\":\"3m\",\"timeSpent\":\"6m\",\"originalEstimateSeconds\":600,\"remainingEstimateSeconds\":200,\"timeSpentSeconds\":400}}}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if the board does not exist or the user does not have permission to view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/board/{boardId}/configuration": { "get": { "tags": [ "Board" ], "summary": "Get configuration", "description": "Get the board configuration. The response contains the following fields:\n\n* `id` \\- ID of the board.\n* `name` \\- Name of the board.\n* `filter` \\- Reference to the filter used by the given board.\n* `location` \\- Reference to the container that the board is located in. Includes the container type (Valid values: project, user).\n* `subQuery` (Kanban only) - JQL subquery used by the given board.\n* `columnConfig` \\- The column configuration lists the columns for the board, in the order defined in the column configuration. For each column, it shows the issue status mapping as well as the constraint type (Valid values: none, issueCount, issueCountExclSubs) for the min/max number of issues. Note, the last column with statuses mapped to it is treated as the \"Done\" column, which means that issues in that column will be marked as already completed.\n* `estimation` (Scrum only) - Contains information about type of estimation used for the board. Valid values: none, issueCount, field. If the estimation type is \"field\", the ID and display name of the field used for estimation is also returned. Note, estimates for an issue can be updated by a PUT /rest/api/~ver~/issue/{issueIdOrKey} request, however the fields must be on the screen. \"timeoriginalestimate\" field will never be on the screen, so in order to update it \"originalEstimate\" in \"timetracking\" field should be updated.\n* `ranking` \\- Contains information about custom field used for ranking in the given board.", "operationId": "com.atlassian.greenhopper.api.rest.BoardResource.getConfiguration_get", "parameters": [ { "name": "boardId", "in": "path", "description": "The ID of the board for which configuration is requested.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Returns the configuration of the board for given boardId.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "type": { "type": "string" }, "self": { "type": "string", "format": "uri" }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "projectKeyOrId": { "type": "string" } } }, "filter": { "type": "object", "properties": { "id": { "type": "string" }, "self": { "type": "string", "format": "uri" } } }, "subQuery": { "type": "object", "properties": { "query": { "type": "string" } } }, "columnConfig": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "statuses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "self": { "type": "string", "format": "uri" } } } }, "min": { "type": "integer", "format": "int32" }, "max": { "type": "integer", "format": "int32" } } } }, "constraintType": { "type": "string" } } }, "estimation": { "type": "object", "properties": { "type": { "type": "string" }, "field": { "type": "object", "properties": { "fieldId": { "type": "string" }, "displayName": { "type": "string" } } } } }, "ranking": { "type": "object", "properties": { "rankCustomFieldId": { "type": "integer", "format": "int64" } } } } }, "examples": { "response": { "value": "{\"id\":10000,\"name\":\"Board\",\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/84/config\",\"location\":{\"type\":\"project\",\"key\":\"PROJ\",\"id\":\"10010\",\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/project/10010\",\"name\":\"name\"},\"filter\":{\"id\":\"1001\",\"self\":\"http://your-domain.atlassian.net/filter/1001\"},\"columnConfig\":{\"columns\":[{\"name\":\"To Do\",\"statuses\":[{\"id\":\"1\",\"self\":\"http://your-domain.atlassian.net/status/1\"},{\"id\":\"4\",\"self\":\"http://your-domain.atlassian.net/status/4\"}]},{\"name\":\"In progress\",\"statuses\":[{\"id\":\"3\",\"self\":\"http://your-domain.atlassian.net/status/3\"}],\"min\":2,\"max\":4},{\"name\":\"Done\",\"statuses\":[{\"id\":\"5\",\"self\":\"http://your-domain.atlassian.net/status/5\"}]}],\"constraintType\":\"issueCount\"},\"estimation\":{\"type\":\"field\",\"field\":{\"fieldId\":\"customfield_10002\",\"displayName\":\"Story Points\"}},\"ranking\":{\"rankCustomFieldId\":10020}}" } } } } }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if user does not a have valid license." }, "404": { "description": "Returned if board does not exist or the user cannot view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/board/{boardId}/epic": { "get": { "tags": [ "Board" ], "summary": "Get epics", "description": "Returns all epics from the board, for the given board ID. This only includes epics that the user has permission to view. Note, if the user does not have permission to view the board, no epics will be returned at all.", "operationId": "com.atlassian.greenhopper.api.rest.BoardEpicResource.getEpics_get", "parameters": [ { "name": "boardId", "in": "path", "description": "The ID of the board that contains the requested epics.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "startAt", "in": "query", "description": "The starting index of the returned epics. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of epics to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "done", "in": "query", "description": "Filters results to epics that are either done or not done. Valid values: true, false.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the requested epics, at the specified page of the results.", "content": { "application/json": { "examples": { "response": { "value": "{\"maxResults\":2,\"startAt\":1,\"total\":5,\"isLast\":false,\"values\":[{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/epic/23\",\"name\":\"epic 1\",\"summary\":\"epic 1 summary\",\"color\":{\"key\":\"color_4\"},\"done\":true},{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/epic/13\",\"name\":\"epic 2\",\"summary\":\"epic 2 summary\",\"color\":{\"key\":\"color_2\"},\"done\":false}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not have valid license." }, "404": { "description": "Returned if board does not exist or the user does not have permission to view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/board/{boardId}/epic/none/issue": { "get": { "tags": [ "Board" ], "summary": "Get issues without epic", "description": "Returns all issues that do not belong to any epic on a board, for a given board ID. This only includes issues that the user has permission to view. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank.", "operationId": "com.atlassian.greenhopper.api.rest.BoardEpicResource.getIssuesWithoutEpic_get", "parameters": [ { "name": "boardId", "in": "path", "description": "The ID of the board that contains the requested issues.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "startAt", "in": "query", "description": "The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of issues to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details. Note, the total number of issues returned is limited by the property 'jira.search.views.default.max' in your Jira instance. If you exceed this limit, your results will be truncated.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "jql", "in": "query", "description": "Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues. \nNote that `username` and `userkey` have been deprecated as search terms for this parameter. See the [migration guide](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. Use `accountId` instead.", "required": false, "schema": { "type": "string" } }, { "name": "validateQuery", "in": "query", "description": "Specifies whether to validate the JQL query or not. Default: true.", "required": false, "schema": { "type": "boolean" } }, { "name": "fields", "in": "query", "description": "The list of fields to return for each issue. By default, all navigable and Agile fields are returned.", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "expand", "in": "query", "description": "A comma-separated list of the parameters to expand.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the requested issues, at the specified page of the results.", "content": { "application/json": { "examples": { "response": { "value": "{\"expand\":\"names,schema\",\"startAt\":0,\"maxResults\":50,\"total\":1,\"issues\":[{\"expand\":\"\",\"id\":\"10001\",\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001\",\"key\":\"HSP-1\",\"fields\":{\"flagged\":true,\"sprint\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/13\",\"state\":\"future\",\"name\":\"sprint 2\",\"goal\":\"sprint 2 goal\"},\"closedSprints\":[{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/23\",\"state\":\"closed\",\"name\":\"sprint 1\",\"startDate\":\"2015-04-11T15:22:00.000+10:00\",\"endDate\":\"2015-04-20T01:22:00.000+10:00\",\"completeDate\":\"2015-04-20T11:04:00.000+10:00\",\"goal\":\"sprint 1 goal\"}],\"description\":\"example bug report\",\"project\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/project/EX\",\"id\":\"10000\",\"key\":\"EX\",\"name\":\"Example\",\"avatarUrls\":{\"48x48\":\"http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000\",\"24x24\":\"http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000\",\"16x16\":\"http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000\",\"32x32\":\"http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000\"},\"projectCategory\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000\",\"id\":\"10000\",\"name\":\"FIRST\",\"description\":\"First Project Category\"},\"simplified\":false,\"style\":\"classic\"},\"comment\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000\",\"id\":\"10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"body\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.\"}]}]},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"created\":\"2019-07-22T05:46:06.698+0000\",\"updated\":\"2019-07-22T05:46:06.699+0000\",\"visibility\":{\"type\":\"role\",\"value\":\"Administrators\"}}],\"epic\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/epic/23\",\"name\":\"epic 1\",\"summary\":\"epic 1 summary\",\"color\":{\"key\":\"color_4\"},\"done\":true},\"worklog\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"comment\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"I did some work here.\"}]}]},\"updated\":\"2019-07-22T05:46:06.706+0000\",\"visibility\":{\"type\":\"group\",\"value\":\"jira-developers\"},\"started\":\"2019-07-22T05:46:06.706+0000\",\"timeSpent\":\"3h 20m\",\"timeSpentSeconds\":12000,\"id\":\"100028\",\"issueId\":\"10002\"}],\"updated\":1,\"timetracking\":{\"originalEstimate\":\"10m\",\"remainingEstimate\":\"3m\",\"timeSpent\":\"6m\",\"originalEstimateSeconds\":600,\"remainingEstimateSeconds\":200,\"timeSpentSeconds\":400}}}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if the board does not exist or the user does not have permission to view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/board/{boardId}/epic/{epicId}/issue": { "get": { "tags": [ "Board" ], "summary": "Get issues for epic", "description": "Returns all issues that belong to an epic on the board, for the given epic ID and the board ID. This only includes issues that the user has permission to view. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank.", "operationId": "com.atlassian.greenhopper.api.rest.BoardEpicResource.getIssuesForEpic_get", "parameters": [ { "name": "boardId", "in": "path", "description": "The ID of the board that contains the requested issues.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "epicId", "in": "path", "description": "The ID of the epic that contains the requested issues.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "startAt", "in": "query", "description": "The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of issues to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details. Note, the total number of issues returned is limited by the property 'jira.search.views.default.max' in your Jira instance. If you exceed this limit, your results will be truncated.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "jql", "in": "query", "description": "Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues.", "required": false, "schema": { "type": "string" } }, { "name": "validateQuery", "in": "query", "description": "Specifies whether to validate the JQL query or not. Default: true.", "required": false, "schema": { "type": "boolean" } }, { "name": "fields", "in": "query", "description": "The list of fields to return for each issue. By default, all navigable and Agile fields are returned.", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "expand", "in": "query", "description": "A comma-separated list of the parameters to expand.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the requested issues, at the specified page of the results.", "content": { "application/json": { "examples": { "response": { "value": "{\"expand\":\"names,schema\",\"startAt\":0,\"maxResults\":50,\"total\":1,\"issues\":[{\"expand\":\"\",\"id\":\"10001\",\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001\",\"key\":\"HSP-1\",\"fields\":{\"flagged\":true,\"sprint\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/13\",\"state\":\"future\",\"name\":\"sprint 2\",\"goal\":\"sprint 2 goal\"},\"closedSprints\":[{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/23\",\"state\":\"closed\",\"name\":\"sprint 1\",\"startDate\":\"2015-04-11T15:22:00.000+10:00\",\"endDate\":\"2015-04-20T01:22:00.000+10:00\",\"completeDate\":\"2015-04-20T11:04:00.000+10:00\",\"goal\":\"sprint 1 goal\"}],\"description\":\"example bug report\",\"project\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/project/EX\",\"id\":\"10000\",\"key\":\"EX\",\"name\":\"Example\",\"avatarUrls\":{\"48x48\":\"http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000\",\"24x24\":\"http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000\",\"16x16\":\"http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000\",\"32x32\":\"http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000\"},\"projectCategory\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000\",\"id\":\"10000\",\"name\":\"FIRST\",\"description\":\"First Project Category\"},\"simplified\":false,\"style\":\"classic\"},\"comment\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000\",\"id\":\"10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"body\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.\"}]}]},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"created\":\"2019-07-22T05:46:06.698+0000\",\"updated\":\"2019-07-22T05:46:06.699+0000\",\"visibility\":{\"type\":\"role\",\"value\":\"Administrators\"}}],\"epic\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/epic/23\",\"name\":\"epic 1\",\"summary\":\"epic 1 summary\",\"color\":{\"key\":\"color_4\"},\"done\":true},\"worklog\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"comment\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"I did some work here.\"}]}]},\"updated\":\"2019-07-22T05:46:06.706+0000\",\"visibility\":{\"type\":\"group\",\"value\":\"jira-developers\"},\"started\":\"2019-07-22T05:46:06.706+0000\",\"timeSpent\":\"3h 20m\",\"timeSpentSeconds\":12000,\"id\":\"100028\",\"issueId\":\"10002\"}],\"updated\":1,\"timetracking\":{\"originalEstimate\":\"10m\",\"remainingEstimate\":\"3m\",\"timeSpent\":\"6m\",\"originalEstimateSeconds\":600,\"remainingEstimateSeconds\":200,\"timeSpentSeconds\":400}}}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if the board does not exist or the user does not have permission to view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/board/{boardId}/features": { "get": { "tags": [ "Board" ], "summary": "Get features for board", "description": "", "operationId": "com.atlassian.greenhopper.api.rest.BoardFeaturesResource.getFeaturesForBoard_get", "parameters": [ { "name": "boardId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "type": "object", "properties": { "features": { "type": "array", "items": { "type": "object" } } } } } } } }, "deprecated": false, "x-atlassian-connect-scope": "READ" }, "put": { "tags": [ "Board" ], "summary": "Toggle features", "description": "", "operationId": "com.atlassian.greenhopper.api.rest.BoardFeaturesResource.toggleFeatures_put", "parameters": [ { "name": "boardId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "type": "object", "properties": { "features": { "type": "array", "items": { "type": "object" } } } } } } } }, "deprecated": false, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "boardId": { "type": "integer", "format": "int64" }, "feature": { "type": "string" }, "enabling": { "type": "boolean" } } } } }, "required": true }, "x-atlassian-connect-scope": "WRITE" } }, "/agile/1.0/board/{boardId}/issue": { "get": { "tags": [ "Board" ], "summary": "Get issues for board", "description": "Returns all issues from a board, for a given board ID. This only includes issues that the user has permission to view. An issue belongs to the board if its status is mapped to the board's column. Epic issues do not belongs to the scrum boards. Note, if the user does not have permission to view the board, no issues will be returned at all. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank.", "operationId": "com.atlassian.greenhopper.api.rest.BoardResource.getIssuesForBoard_get", "parameters": [ { "name": "boardId", "in": "path", "description": "The ID of the board that contains the requested issues.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "startAt", "in": "query", "description": "The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of issues to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details. Note, the total number of issues returned is limited by the property 'jira.search.views.default.max' in your Jira instance. If you exceed this limit, your results will be truncated.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "jql", "in": "query", "description": "Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues. \nNote that `username` and `userkey` have been deprecated as search terms for this parameter. See the [migration guide](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. Use `accountId` instead.", "required": false, "schema": { "type": "string" } }, { "name": "validateQuery", "in": "query", "description": "Specifies whether to validate the JQL query or not. Default: true.", "required": false, "schema": { "type": "boolean" } }, { "name": "fields", "in": "query", "description": "The list of fields to return for each issue. By default, all navigable and Agile fields are returned.", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "expand", "in": "query", "description": "This parameter is currently not used.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the requested issues, at the specified page of the results.", "content": { "application/json": { "examples": { "response": { "value": "{\"expand\":\"names,schema\",\"startAt\":0,\"maxResults\":50,\"total\":1,\"issues\":[{\"expand\":\"\",\"id\":\"10001\",\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001\",\"key\":\"HSP-1\",\"fields\":{\"flagged\":true,\"sprint\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/13\",\"state\":\"future\",\"name\":\"sprint 2\",\"goal\":\"sprint 2 goal\"},\"closedSprints\":[{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/23\",\"state\":\"closed\",\"name\":\"sprint 1\",\"startDate\":\"2015-04-11T15:22:00.000+10:00\",\"endDate\":\"2015-04-20T01:22:00.000+10:00\",\"completeDate\":\"2015-04-20T11:04:00.000+10:00\",\"goal\":\"sprint 1 goal\"}],\"description\":\"example bug report\",\"project\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/project/EX\",\"id\":\"10000\",\"key\":\"EX\",\"name\":\"Example\",\"avatarUrls\":{\"48x48\":\"http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000\",\"24x24\":\"http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000\",\"16x16\":\"http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000\",\"32x32\":\"http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000\"},\"projectCategory\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000\",\"id\":\"10000\",\"name\":\"FIRST\",\"description\":\"First Project Category\"},\"simplified\":false,\"style\":\"classic\"},\"comment\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000\",\"id\":\"10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"body\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.\"}]}]},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"created\":\"2019-07-22T05:46:06.698+0000\",\"updated\":\"2019-07-22T05:46:06.699+0000\",\"visibility\":{\"type\":\"role\",\"value\":\"Administrators\"}}],\"epic\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/epic/23\",\"name\":\"epic 1\",\"summary\":\"epic 1 summary\",\"color\":{\"key\":\"color_4\"},\"done\":true},\"worklog\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"comment\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"I did some work here.\"}]}]},\"updated\":\"2019-07-22T05:46:06.706+0000\",\"visibility\":{\"type\":\"group\",\"value\":\"jira-developers\"},\"started\":\"2019-07-22T05:46:06.706+0000\",\"timeSpent\":\"3h 20m\",\"timeSpentSeconds\":12000,\"id\":\"100028\",\"issueId\":\"10002\"}],\"updated\":1,\"timetracking\":{\"originalEstimate\":\"10m\",\"remainingEstimate\":\"3m\",\"timeSpent\":\"6m\",\"originalEstimateSeconds\":600,\"remainingEstimateSeconds\":200,\"timeSpentSeconds\":400}}}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if the board does not exist or the user does not have permission to view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" }, "post": { "tags": [ "Board" ], "summary": "Move issues to board", "description": "Move issues from the backog to the board (if they are already in the backlog of that board). \nThis operation either moves an issue(s) onto a board from the backlog (by adding it to the issueList for the board) Or transitions the issue(s) to the first column for a kanban board with backlog. At most 50 issues may be moved at once.", "operationId": "com.atlassian.greenhopper.api.rest.BoardResource.moveIssuesToBoard_post", "parameters": [ { "name": "boardId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Empty response is returned if operation was successful." }, "207": { "description": "Returns the list of issue with status of rank operation.", "content": { "application/json": { "examples": { "response": { "value": "{\"entries\":[{\"issueId\":10000,\"issueKey\":\"PR-1\",\"status\":200},{\"issueId\":10001,\"issueKey\":\"PR-2\",\"status\":200},{\"issueId\":10002,\"issueKey\":\"PR-3\",\"status\":503,\"errors\":[\"JIRA Agile cannot execute the rank operation at this time. Please try again later.\"]}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if user does not a have valid license or does not have permission to assign issues." } }, "deprecated": false, "requestBody": { "$ref": "#/components/requestBodies/com.atlassian.greenhopper.api.rest.BacklogResource.moveIssuesToBacklogForBoard_postIssuerankrequestbean" }, "x-atlassian-connect-scope": "WRITE" } }, "/agile/1.0/board/{boardId}/project": { "get": { "tags": [ "Board" ], "summary": "Get projects", "description": "Returns all projects that are associated with the board, for the given board ID. If the user does not have permission to view the board, no projects will be returned at all. Returned projects are ordered by the name.\n\nA project is associated with a board if the board filter contains reference the project or there is an issue from the project that belongs to the board.\n\nThe board filter contains reference the project only if JQL query guarantees that returned issues will be returned from the project set defined in JQL. For instance the query `project in (ABC, BCD) AND reporter = admin` have reference to ABC and BCD projects but query `project in (ABC, BCD) OR reporter = admin` doesn't have reference to any project.\n\nAn issue belongs to the board if its status is mapped to the board's column. Epic issues do not belongs to the scrum boards.", "operationId": "com.atlassian.greenhopper.api.rest.BoardProjectResource.getProjects_get", "parameters": [ { "name": "boardId", "in": "path", "description": "The ID of the board that contains returned projects.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "startAt", "in": "query", "description": "The starting index of the returned projects. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of projects to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Returns the board's projects, at the specified page of the results.", "content": { "application/json": { "examples": { "response": { "value": "{\"maxResults\":10,\"startAt\":0,\"total\":2,\"isLast\":true,\"values\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/project/EX\",\"id\":\"10000\",\"key\":\"EX\",\"name\":\"Example\",\"avatarUrls\":{\"48x48\":\"http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000\",\"24x24\":\"http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000\",\"16x16\":\"http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000\",\"32x32\":\"http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000\"},\"projectCategory\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000\",\"id\":\"10000\",\"name\":\"FIRST\",\"description\":\"First Project Category\"},\"simplified\":false,\"style\":\"classic\"},{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/project/ABC\",\"id\":\"10001\",\"key\":\"ABC\",\"name\":\"Alphabetical\",\"avatarUrls\":{\"48x48\":\"http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10001\",\"24x24\":\"http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10001\",\"16x16\":\"http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10001\",\"32x32\":\"http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10001\"},\"projectCategory\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000\",\"id\":\"10000\",\"name\":\"FIRST\",\"description\":\"First Project Category\"},\"simplified\":false,\"style\":\"classic\"}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if board does not exist or the user does not have permission to access it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/board/{boardId}/project/full": { "get": { "tags": [ "Board" ], "summary": "Get projects full", "description": "Returns all projects that are statically associated with the board, for the given board ID. Returned projects are ordered by the name.\n\nA project is associated with a board if the board filter contains reference the project.\n\nThe board filter contains reference the project only if JQL query guarantees that returned issues will be returned from the project set defined in JQL. For instance the query `project in (ABC, BCD) AND reporter = admin` have reference to ABC and BCD projects but query `project in (ABC, BCD) OR reporter = admin` doesn't have reference to any project.", "operationId": "com.atlassian.greenhopper.api.rest.BoardProjectResource.getProjectsFull_get", "parameters": [ { "name": "boardId", "in": "path", "description": "The ID of the board that contains returned projects.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Returns the board's projects, at the specified page of the results." }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if board does not exist or the user does not have permission to access it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/board/{boardId}/properties": { "get": { "tags": [ "Board" ], "summary": "Get board property keys", "description": "Returns the keys of all properties for the board identified by the id. The user who retrieves the property keys is required to have permissions to view the board.", "operationId": "com.atlassian.greenhopper.api.rest.BoardPropertyResource.getBoardPropertyKeys_get", "parameters": [ { "name": "boardId", "in": "path", "description": "the ID of the board from which property keys will be returned.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the board with given id exists.", "content": { "application/json": { "examples": { "response": { "value": "com.atlassian.jira.rest.v2.entity.property.EntityPropertyResourceExamples#GET_PROPERTIES_KEYS_RESPONSE_200" } } } } }, "400": { "description": "Returned if the boardId is invalid (negative or not a number)." }, "401": { "description": "Returned if the calling user is not authenticated." }, "404": { "description": "Returned if the board with given id does not exist, or if the property with given key is not found, or the user doesn't have permissions to see it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/board/{boardId}/properties/{propertyKey}": { "get": { "tags": [ "Board" ], "summary": "Get board property", "description": "Returns the value of the property with a given key from the board identified by the provided id. The user who retrieves the property is required to have permissions to view the board.", "operationId": "com.atlassian.greenhopper.api.rest.BoardPropertyResource.getBoardProperty_get", "parameters": [ { "name": "boardId", "in": "path", "description": "the ID of the board from which the property will be returned.", "required": true, "schema": { "type": "string" } }, { "name": "propertyKey", "in": "path", "description": "the key of the property to return.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the board exists and the property was found.", "content": { "application/json": { "examples": { "response": { "value": "com.atlassian.jira.rest.v2.entity.property.EntityPropertyResourceExamples#GET_PROPERTY_RESPONSE_200" } } } } }, "400": { "description": "Returned if the boardId is invalid (negative or not a number)." }, "401": { "description": "Returned if the calling user is not authenticated." }, "404": { "description": "Returned if the board with given id does not exist, or if the property with given key is not found, or the user doesn't have permissions to see it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" }, "put": { "tags": [ "Board" ], "summary": "Set board property", "description": "Sets the value of the specified board's property.\n\nYou can use this resource to store a custom data against the board identified by the id. The user who stores the data is required to have permissions to modify the board.", "operationId": "com.atlassian.greenhopper.api.rest.BoardPropertyResource.setBoardProperty_put", "parameters": [ { "name": "boardId", "in": "path", "description": "the ID of the board on which the property will be set.", "required": true, "schema": { "type": "string" } }, { "name": "propertyKey", "in": "path", "description": "the key of the board's property. The maximum length of the key is 255 bytes.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the board property is successfully updated." }, "201": { "description": "Returned if the board property is successfully created." }, "400": { "description": "Returned if the boardId is invalid (negative or not a number)." }, "401": { "description": "Returned if the calling user is not authenticated." }, "404": { "description": "Returned if the board with given id does not exist or the user doesn't have permissions to see it." } }, "deprecated": false, "x-atlassian-connect-scope": "WRITE" }, "delete": { "tags": [ "Board" ], "summary": "Delete board property", "description": "Removes the property from the board identified by the id. Ths user removing the property is required to have permissions to modify the board.", "operationId": "com.atlassian.greenhopper.api.rest.BoardPropertyResource.deleteBoardProperty_delete", "parameters": [ { "name": "boardId", "in": "path", "description": "the id of the board from which the property will be removed.", "required": true, "schema": { "type": "string" } }, { "name": "propertyKey", "in": "path", "description": "the key of the property to remove.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returned if the board property was removed successfully." }, "400": { "description": "Returned if the boardId is invalid (negative or not a number)." }, "401": { "description": "Returned if the calling user is not authenticated." }, "404": { "description": "Returned if the board with given id does not exist, or if the property with given key is not found, or the user doesn't have permissions to see it." } }, "deprecated": false, "x-atlassian-connect-scope": "DELETE" } }, "/agile/1.0/board/{boardId}/quickfilter": { "get": { "tags": [ "Board" ], "summary": "Get all quick filters", "description": "Returns all quick filters from a board, for a given board ID.", "operationId": "com.atlassian.greenhopper.api.rest.BoardQuickFilterResource.getAllQuickFilters_get", "parameters": [ { "name": "boardId", "in": "path", "description": "The ID of the board that contains the requested quick filters.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "startAt", "in": "query", "description": "The starting index of the returned quick filters. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of sprints to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Returns the requested quick filters, at the specified page of the results. Quick filters will be ordered first by position.", "content": { "application/json": { "schema": { "type": "object", "properties": { "maxResults": { "type": "integer", "format": "int32" }, "startAt": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" }, "isLast": { "type": "boolean" }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "boardId": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "jql": { "type": "string" }, "description": { "type": "string" }, "position": { "type": "integer", "format": "int32" } } } } } }, "examples": { "response": { "value": "{\"maxResults\":2,\"startAt\":1,\"total\":5,\"isLast\":false,\"values\":[{\"id\":1,\"boardId\":1,\"name\":\"Bugs\",\"jql\":\"issueType = bug\",\"description\":\"Issues of type bug\",\"position\":0},{\"id\":2,\"boardId\":1,\"name\":\"Tasks\",\"jql\":\"issueType = task\",\"description\":\"Issues of type task\",\"position\":0}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if board does not exist or the user does not have permission to view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/board/{boardId}/quickfilter/{quickFilterId}": { "get": { "tags": [ "Board" ], "summary": "Get quick filter", "description": "Returns the quick filter for a given quick filter ID. The quick filter will only be returned if the user can view the board that the quick filter belongs to.", "operationId": "com.atlassian.greenhopper.api.rest.BoardQuickFilterResource.getQuickFilter_get", "parameters": [ { "name": "boardId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "quickFilterId", "in": "path", "description": "The ID of the requested quick filter.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Returns the requested quick filter.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "boardId": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "jql": { "type": "string" }, "description": { "type": "string" }, "position": { "type": "integer", "format": "int32" } } }, "examples": { "response": { "value": "{\"id\":1,\"boardId\":1,\"name\":\"Bugs\",\"jql\":\"issueType = bug\",\"description\":\"Issues of type bug\",\"position\":0}" } } } } }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if the board with given id does not exist or if the quick filter with given id is not found or the user doesn't have permissions to see it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/board/{boardId}/reports": { "get": { "tags": [ "Board" ], "summary": "Get reports for board", "description": "", "operationId": "com.atlassian.greenhopper.api.rest.BoardReportsResource.getReportsForBoard_get", "parameters": [ { "name": "boardId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reports": { "type": "array", "items": { "type": "object" } } } } } } } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/board/{boardId}/sprint": { "get": { "tags": [ "Board" ], "summary": "Get all sprints", "description": "Returns all sprints from a board, for a given board ID. This only includes sprints that the user has permission to view.", "operationId": "com.atlassian.greenhopper.api.rest.BoardSprintResource.getAllSprints_get", "parameters": [ { "name": "boardId", "in": "path", "description": "The ID of the board that contains the requested sprints.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "startAt", "in": "query", "description": "The starting index of the returned sprints. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of sprints to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "state", "in": "query", "description": "Filters results to sprints in specified states. Valid values: future, active, closed. You can define multiple states separated by commas, e.g. state=active,closed", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the requested sprints, at the specified page of the results. Sprints will be ordered first by state (i.e. closed, active, future) then by their position in the backlog.", "content": { "application/json": { "examples": { "response": { "value": "{\"maxResults\":2,\"startAt\":1,\"total\":5,\"isLast\":false,\"values\":[{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/23\",\"state\":\"closed\",\"name\":\"sprint 1\",\"startDate\":\"2015-04-11T15:22:00.000+10:00\",\"endDate\":\"2015-04-20T01:22:00.000+10:00\",\"completeDate\":\"2015-04-20T11:04:00.000+10:00\",\"originBoardId\":5,\"goal\":\"sprint 1 goal\"},{\"id\":72,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/73\",\"state\":\"future\",\"name\":\"sprint 2\",\"goal\":\"sprint 2 goal\"}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if board does not exist or the user does not have permission to view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/board/{boardId}/sprint/{sprintId}/issue": { "get": { "tags": [ "Board" ], "summary": "Get issues for sprint", "description": "Get all issues you have access to that belong to the sprint from the board. Issue returned from this resource contains additional fields like: sprint, closedSprints, flagged and epic. Issues are returned ordered by rank. JQL order has higher priority than default rank.", "operationId": "com.atlassian.greenhopper.api.rest.BoardSprintResource.getIssuesForSprint_get", "parameters": [ { "name": "boardId", "in": "path", "description": "The ID of the board that contains requested issues.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "sprintId", "in": "path", "description": "The ID of the sprint that contains requested issues.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "startAt", "in": "query", "description": "The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of issues to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details. Note, the total number of issues returned is limited by the property 'jira.search.views.default.max' in your Jira instance. If you exceed this limit, your results will be truncated.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "jql", "in": "query", "description": "Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues. \nNote that `username` and `userkey` have been deprecated as search terms for this parameter. See the [migration guide](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. Use `accountId` instead.", "required": false, "schema": { "type": "string" } }, { "name": "validateQuery", "in": "query", "description": "Specifies whether to validate the JQL query or not. Default: true.", "required": false, "schema": { "type": "boolean" } }, { "name": "fields", "in": "query", "description": "The list of fields to return for each issue. By default, all navigable and Agile fields are returned.", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "expand", "in": "query", "description": "A comma-separated list of the parameters to expand.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the requested issues, at the specified page of the results.", "content": { "application/json": { "examples": { "response": { "value": "{\"expand\":\"names,schema\",\"startAt\":0,\"maxResults\":50,\"total\":1,\"issues\":[{\"expand\":\"\",\"id\":\"10001\",\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001\",\"key\":\"HSP-1\",\"fields\":{\"flagged\":true,\"sprint\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/13\",\"state\":\"future\",\"name\":\"sprint 2\",\"goal\":\"sprint 2 goal\"},\"closedSprints\":[{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/23\",\"state\":\"closed\",\"name\":\"sprint 1\",\"startDate\":\"2015-04-11T15:22:00.000+10:00\",\"endDate\":\"2015-04-20T01:22:00.000+10:00\",\"completeDate\":\"2015-04-20T11:04:00.000+10:00\",\"goal\":\"sprint 1 goal\"}],\"description\":\"example bug report\",\"project\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/project/EX\",\"id\":\"10000\",\"key\":\"EX\",\"name\":\"Example\",\"avatarUrls\":{\"48x48\":\"http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000\",\"24x24\":\"http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000\",\"16x16\":\"http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000\",\"32x32\":\"http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000\"},\"projectCategory\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000\",\"id\":\"10000\",\"name\":\"FIRST\",\"description\":\"First Project Category\"},\"simplified\":false,\"style\":\"classic\"},\"comment\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000\",\"id\":\"10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"body\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.\"}]}]},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"created\":\"2019-07-22T05:46:06.698+0000\",\"updated\":\"2019-07-22T05:46:06.699+0000\",\"visibility\":{\"type\":\"role\",\"value\":\"Administrators\"}}],\"epic\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/epic/23\",\"name\":\"epic 1\",\"summary\":\"epic 1 summary\",\"color\":{\"key\":\"color_4\"},\"done\":true},\"worklog\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"comment\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"I did some work here.\"}]}]},\"updated\":\"2019-07-22T05:46:06.706+0000\",\"visibility\":{\"type\":\"group\",\"value\":\"jira-developers\"},\"started\":\"2019-07-22T05:46:06.706+0000\",\"timeSpent\":\"3h 20m\",\"timeSpentSeconds\":12000,\"id\":\"100028\",\"issueId\":\"10002\"}],\"updated\":1,\"timetracking\":{\"originalEstimate\":\"10m\",\"remainingEstimate\":\"3m\",\"timeSpent\":\"6m\",\"originalEstimateSeconds\":600,\"remainingEstimateSeconds\":200,\"timeSpentSeconds\":400}}}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if the board does not exist or the user does not have permission to view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/board/{boardId}/version": { "get": { "tags": [ "Board" ], "summary": "Get all versions", "description": "Returns all versions from a board, for a given board ID. This only includes versions that the user has permission to view. Note, if the user does not have permission to view the board, no versions will be returned at all. Returned versions are ordered by the name of the project from which they belong and then by sequence defined by user.", "operationId": "com.atlassian.greenhopper.api.rest.BoardVersionResource.getAllVersions_get", "parameters": [ { "name": "boardId", "in": "path", "description": "The ID of the board that contains the requested versions.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "startAt", "in": "query", "description": "The starting index of the returned versions. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of versions to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "released", "in": "query", "description": "Filters results to versions that are either released or unreleased. Valid values: true, false.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the requested versions, at the specified page of the results.", "content": { "application/json": { "examples": { "response": { "value": "{\"maxResults\":2,\"startAt\":1,\"total\":5,\"isLast\":false,\"values\":[{\"self\":\"http://your-domain.atlassian.net/version/10000\",\"id\":10000,\"projectId\":10000,\"name\":\"Version 1\",\"description\":\"A first version\",\"archived\":false,\"released\":true,\"releaseDate\":\"2015-04-20T01:02:00.000+10:00\"},{\"self\":\"http://your-domain.atlassian.net/version/10010\",\"id\":10010,\"projectId\":10000,\"name\":\"Next Version\",\"description\":\"Minor Bugfix version\",\"archived\":false,\"released\":false}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if board does not exist or the user does not have permission to view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/epic/none/issue": { "get": { "tags": [ "Epic" ], "summary": "Get issues without epic", "description": "Returns all issues that do not belong to any epic. This only includes issues that the user has permission to view. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank. **Note:** If you are querying a next-gen project, do not use this operation. Instead, search for issues that don't belong to an epic by using the [Search for issues using JQL](https://developer.atlassian.com/cloud/jira/platform/rest/v2/#api-rest-api-2-search-get) operation in the Jira platform REST API. Build your JQL query using the `parent is empty` clause. For more information on the `parent` JQL field, see [Advanced searching](https://confluence.atlassian.com/x/dAiiLQ#Advancedsearching-fieldsreference-Parent).", "operationId": "com.atlassian.greenhopper.api.rest.EpicResource.getIssuesWithoutEpic_get", "parameters": [ { "name": "startAt", "in": "query", "description": "The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of issues to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details. Note, the total number of issues returned is limited by the property 'jira.search.views.default.max' in your Jira instance. If you exceed this limit, your results will be truncated.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "jql", "in": "query", "description": "Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues.", "required": false, "schema": { "type": "string" } }, { "name": "validateQuery", "in": "query", "description": "Specifies whether to validate the JQL query or not. Default: true.", "required": false, "schema": { "type": "boolean" } }, { "name": "fields", "in": "query", "description": "The list of fields to return for each issue. By default, all navigable and Agile fields are returned.", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "expand", "in": "query", "description": "A comma-separated list of the parameters to expand.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the requested issues, at the specified page of the results.", "content": { "application/json": { "examples": { "response": { "value": "{\"expand\":\"names,schema\",\"startAt\":0,\"maxResults\":50,\"total\":1,\"issues\":[{\"expand\":\"\",\"id\":\"10001\",\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001\",\"key\":\"HSP-1\",\"fields\":{\"flagged\":true,\"sprint\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/13\",\"state\":\"future\",\"name\":\"sprint 2\",\"goal\":\"sprint 2 goal\"},\"closedSprints\":[{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/23\",\"state\":\"closed\",\"name\":\"sprint 1\",\"startDate\":\"2015-04-11T15:22:00.000+10:00\",\"endDate\":\"2015-04-20T01:22:00.000+10:00\",\"completeDate\":\"2015-04-20T11:04:00.000+10:00\",\"goal\":\"sprint 1 goal\"}],\"description\":\"example bug report\",\"project\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/project/EX\",\"id\":\"10000\",\"key\":\"EX\",\"name\":\"Example\",\"avatarUrls\":{\"48x48\":\"http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000\",\"24x24\":\"http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000\",\"16x16\":\"http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000\",\"32x32\":\"http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000\"},\"projectCategory\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000\",\"id\":\"10000\",\"name\":\"FIRST\",\"description\":\"First Project Category\"},\"simplified\":false,\"style\":\"classic\"},\"comment\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000\",\"id\":\"10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"body\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.\"}]}]},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"created\":\"2019-07-22T05:46:06.698+0000\",\"updated\":\"2019-07-22T05:46:06.699+0000\",\"visibility\":{\"type\":\"role\",\"value\":\"Administrators\"}}],\"epic\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/epic/23\",\"name\":\"epic 1\",\"summary\":\"epic 1 summary\",\"color\":{\"key\":\"color_4\"},\"done\":true},\"worklog\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"comment\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"I did some work here.\"}]}]},\"updated\":\"2019-07-22T05:46:06.706+0000\",\"visibility\":{\"type\":\"group\",\"value\":\"jira-developers\"},\"started\":\"2019-07-22T05:46:06.706+0000\",\"timeSpent\":\"3h 20m\",\"timeSpentSeconds\":12000,\"id\":\"100028\",\"issueId\":\"10002\"}],\"updated\":1,\"timetracking\":{\"originalEstimate\":\"10m\",\"remainingEstimate\":\"3m\",\"timeSpent\":\"6m\",\"originalEstimateSeconds\":600,\"remainingEstimateSeconds\":200,\"timeSpentSeconds\":400}}}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" }, "post": { "tags": [ "Epic" ], "summary": "Remove issues from epic", "description": "Removes issues from epics. The user needs to have the edit issue permission for all issue they want to remove from epics. The maximum number of issues that can be moved in one operation is 50. **Note:** This operation does not work for epics in next-gen projects.", "operationId": "com.atlassian.greenhopper.api.rest.EpicResource.removeIssuesFromEpic_post", "responses": { "204": { "description": "Empty response is returned if operation was successful." }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license or does not have permission to assign issues." }, "404": { "description": "Returned if the epic does not exist or the user does not have permission to view it." } }, "deprecated": false, "requestBody": { "$ref": "#/components/requestBodies/com.atlassian.greenhopper.api.rest.BacklogResource.moveIssuesToBacklog_postIssueassignrequestbean" }, "x-atlassian-connect-scope": "WRITE" } }, "/agile/1.0/epic/{epicIdOrKey}": { "get": { "tags": [ "Epic" ], "summary": "Get epic", "description": "Returns the epic for a given epic ID. This epic will only be returned if the user has permission to view it. **Note:** This operation does not work for epics in next-gen projects.", "operationId": "com.atlassian.greenhopper.api.rest.EpicResource.getEpic_get", "parameters": [ { "name": "epicIdOrKey", "in": "path", "description": "The id or key of the requested epic.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the requested epic.", "content": { "application/json": { "examples": { "response": { "value": "{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/epic/23\",\"name\":\"epic 1\",\"summary\":\"epic 1 summary\",\"color\":{\"key\":\"color_4\"},\"done\":true}" } } } } }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if the epic does not exist or the user does not have permission to view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" }, "post": { "tags": [ "Epic" ], "summary": "Partially update epic", "description": "Performs a partial update of the epic. A partial update means that fields not present in the request JSON will not be updated. Valid values for color are `color_1` to `color_9`. **Note:** This operation does not work for epics in next-gen projects.", "operationId": "com.atlassian.greenhopper.api.rest.EpicResource.partiallyUpdateEpic_post", "parameters": [ { "name": "epicIdOrKey", "in": "path", "description": "The id or key of the epic to update.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated epic", "content": { "application/json": { "examples": { "response": { "value": "{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/epic/23\",\"name\":\"epic 1\",\"summary\":\"epic 1 summary\",\"color\":{\"key\":\"color_4\"},\"done\":true}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license or edit issue permission." }, "404": { "description": "Returned if the epic does not exist or the user does not have permission to view it." } }, "deprecated": false, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "color": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "color_1", "color_2", "color_3", "color_4", "color_5", "color_6", "color_7", "color_8", "color_9", "color_10", "color_11", "color_12", "color_13", "color_14" ] } } }, "done": { "type": "boolean" } } }, "examples": { "x-example": { "summary": "Example", "description": "This example was copied over from Swagger V2 into this OAS 3.0 file.", "value": { "name": "epic 2", "summary": "epic 2 summary", "color": { "key": "color_6" }, "done": true } } } } }, "required": true }, "x-atlassian-connect-scope": "WRITE" } }, "/agile/1.0/epic/{epicIdOrKey}/issue": { "get": { "tags": [ "Epic" ], "summary": "Get issues for epic", "description": "Returns all issues that belong to the epic, for the given epic ID. This only includes issues that the user has permission to view. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank. **Note:** If you are querying a next-gen project, do not use this operation. Instead, search for issues that belong to an epic by using the [Search for issues using JQL](https://developer.atlassian.com/cloud/jira/platform/rest/v2/#api-rest-api-2-search-get) operation in the Jira platform REST API. Build your JQL query using the `parent` clause. For more information on the `parent` JQL field, see [Advanced searching](https://confluence.atlassian.com/x/dAiiLQ#Advancedsearching-fieldsreference-Parent).", "operationId": "com.atlassian.greenhopper.api.rest.EpicResource.getIssuesForEpic_get", "parameters": [ { "name": "epicIdOrKey", "in": "path", "description": "The id or key of the epic that contains the requested issues.", "required": true, "schema": { "type": "string" } }, { "name": "startAt", "in": "query", "description": "The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of issues to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details. Note, the total number of issues returned is limited by the property 'jira.search.views.default.max' in your Jira instance. If you exceed this limit, your results will be truncated.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "jql", "in": "query", "description": "Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues. \nNote that `username` and `userkey` have been deprecated as search terms for this parameter. See the [migration guide](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. Use `accountId` instead.", "required": false, "schema": { "type": "string" } }, { "name": "validateQuery", "in": "query", "description": "Specifies whether to validate the JQL query or not. Default: true.", "required": false, "schema": { "type": "boolean" } }, { "name": "fields", "in": "query", "description": "The list of fields to return for each issue. By default, all navigable and Agile fields are returned.", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "expand", "in": "query", "description": "A comma-separated list of the parameters to expand.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the requested issues, at the specified page of the results.", "content": { "application/json": { "examples": { "response": { "value": "{\"expand\":\"names,schema\",\"startAt\":0,\"maxResults\":50,\"total\":1,\"issues\":[{\"expand\":\"\",\"id\":\"10001\",\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001\",\"key\":\"HSP-1\",\"fields\":{\"flagged\":true,\"sprint\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/13\",\"state\":\"future\",\"name\":\"sprint 2\",\"goal\":\"sprint 2 goal\"},\"closedSprints\":[{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/23\",\"state\":\"closed\",\"name\":\"sprint 1\",\"startDate\":\"2015-04-11T15:22:00.000+10:00\",\"endDate\":\"2015-04-20T01:22:00.000+10:00\",\"completeDate\":\"2015-04-20T11:04:00.000+10:00\",\"goal\":\"sprint 1 goal\"}],\"description\":\"example bug report\",\"project\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/project/EX\",\"id\":\"10000\",\"key\":\"EX\",\"name\":\"Example\",\"avatarUrls\":{\"48x48\":\"http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000\",\"24x24\":\"http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000\",\"16x16\":\"http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000\",\"32x32\":\"http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000\"},\"projectCategory\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000\",\"id\":\"10000\",\"name\":\"FIRST\",\"description\":\"First Project Category\"},\"simplified\":false,\"style\":\"classic\"},\"comment\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000\",\"id\":\"10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"body\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.\"}]}]},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"created\":\"2019-07-22T05:46:06.698+0000\",\"updated\":\"2019-07-22T05:46:06.699+0000\",\"visibility\":{\"type\":\"role\",\"value\":\"Administrators\"}}],\"epic\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/epic/23\",\"name\":\"epic 1\",\"summary\":\"epic 1 summary\",\"color\":{\"key\":\"color_4\"},\"done\":true},\"worklog\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"comment\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"I did some work here.\"}]}]},\"updated\":\"2019-07-22T05:46:06.706+0000\",\"visibility\":{\"type\":\"group\",\"value\":\"jira-developers\"},\"started\":\"2019-07-22T05:46:06.706+0000\",\"timeSpent\":\"3h 20m\",\"timeSpentSeconds\":12000,\"id\":\"100028\",\"issueId\":\"10002\"}],\"updated\":1,\"timetracking\":{\"originalEstimate\":\"10m\",\"remainingEstimate\":\"3m\",\"timeSpent\":\"6m\",\"originalEstimateSeconds\":600,\"remainingEstimateSeconds\":200,\"timeSpentSeconds\":400}}}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if the epic does not exist or the user does not have permission to view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" }, "post": { "tags": [ "Epic" ], "summary": "Move issues to epic", "description": "Moves issues to an epic, for a given epic id. Issues can be only in a single epic at the same time. That means that already assigned issues to an epic, will not be assigned to the previous epic anymore. The user needs to have the edit issue permission for all issue they want to move and to the epic. The maximum number of issues that can be moved in one operation is 50. **Note:** This operation does not work for epics in next-gen projects.", "operationId": "com.atlassian.greenhopper.api.rest.EpicResource.moveIssuesToEpic_post", "parameters": [ { "name": "epicIdOrKey", "in": "path", "description": "The id or key of the epic that you want to assign issues to.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Empty response is returned if operation was successful." }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license or does not have edit issue permission for all issues to assign or for the epic." }, "404": { "description": "Returned if the epic does not exist or the user does not have permission to view it." } }, "deprecated": false, "requestBody": { "$ref": "#/components/requestBodies/com.atlassian.greenhopper.api.rest.BacklogResource.moveIssuesToBacklog_postIssueassignrequestbean" }, "x-atlassian-connect-scope": "WRITE" } }, "/agile/1.0/epic/{epicIdOrKey}/rank": { "put": { "tags": [ "Epic" ], "summary": "Rank epics", "description": "Moves (ranks) an epic before or after a given epic.\n\nIf rankCustomFieldId is not defined, the default rank field will be used.\n\n**Note:** This operation does not work for epics in next-gen projects.", "operationId": "com.atlassian.greenhopper.api.rest.EpicResource.rankEpics_put", "parameters": [ { "name": "epicIdOrKey", "in": "path", "description": "The id or key of the epic to rank.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Empty response is returned if operation was successful." }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if user does not a have valid license or does not have permission to rank. To rank issues user have to have schedule issue permission for epics that they want to rank." }, "404": { "description": "Returned when the given epics in the path parameter or the request body do not exist." } }, "deprecated": false, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "rankBeforeEpic": { "type": "string" }, "rankAfterEpic": { "type": "string" }, "rankCustomFieldId": { "type": "integer", "format": "int64" } } }, "examples": { "x-example": { "summary": "Example", "description": "This example was copied over from Swagger V2 into this OAS 3.0 file.", "value": { "rankBeforeEpic": "10000", "rankCustomFieldId": 10521 } } } } }, "description": "bean which contains the information where the given epic should be ranked.", "required": true }, "x-atlassian-connect-scope": "WRITE" } }, "/agile/1.0/issue/rank": { "put": { "tags": [ "Issue" ], "summary": "Rank issues", "description": "Moves (ranks) issues before or after a given issue. At most 50 issues may be ranked at once.\n\nThis operation may fail for some issues, although this will be rare. In that case the 207 status code is returned for the whole response and detailed information regarding each issue is available in the response body.\n\nIf rankCustomFieldId is not defined, the default rank field will be used.", "operationId": "com.atlassian.greenhopper.api.rest.IssueResource.rankIssues_put", "responses": { "204": { "description": "Empty response is returned if operation was successful." }, "207": { "description": "Returns the list of issue with status of rank operation.", "content": { "application/json": { "examples": { "response": { "value": "{\"entries\":[{\"issueId\":10000,\"issueKey\":\"PR-1\",\"status\":200},{\"issueId\":10001,\"issueKey\":\"PR-2\",\"status\":200},{\"issueId\":10002,\"issueKey\":\"PR-3\",\"status\":503,\"errors\":[\"JIRA Agile cannot execute the rank operation at this time. Please try again later.\"]}]}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if user does not a have valid license or does not have permission to rank. To rank issues user has to have schedule issue permission for issues that they want to rank." } }, "deprecated": false, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "string" } }, "rankBeforeIssue": { "type": "string" }, "rankAfterIssue": { "type": "string" }, "rankCustomFieldId": { "type": "integer", "format": "int64" } } }, "examples": { "x-example": { "summary": "Example", "description": "This example was copied over from Swagger V2 into this OAS 3.0 file.", "value": { "issues": [ "PR-1", "10001", "PR-3" ], "rankBeforeIssue": "PR-4", "rankCustomFieldId": 10521 } } } } }, "description": "bean which contains list of issues to rank and information where it should be ranked.", "required": true }, "x-atlassian-connect-scope": "WRITE" } }, "/agile/1.0/issue/{issueIdOrKey}": { "get": { "tags": [ "Issue" ], "summary": "Get issue", "description": "Returns a single issue, for a given issue ID or issue key. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic.", "operationId": "com.atlassian.greenhopper.api.rest.IssueResource.getIssue_get", "parameters": [ { "name": "issueIdOrKey", "in": "path", "description": "The ID or key of the requested issue.", "required": true, "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "The list of fields to return for each issue. By default, all navigable and Agile fields are returned.", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "expand", "in": "query", "description": "A comma-separated list of the parameters to expand.", "required": false, "schema": { "type": "string" } }, { "name": "updateHistory", "in": "query", "description": "A boolean indicating whether the issue retrieved by this method should be added to the current user's issue history", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Returns the requested issue.", "content": { "application/json": { "examples": { "response": { "value": "{\"expand\":\"\",\"id\":\"10001\",\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001\",\"key\":\"HSP-1\",\"fields\":{\"flagged\":true,\"sprint\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/13\",\"state\":\"future\",\"name\":\"sprint 2\",\"goal\":\"sprint 2 goal\"},\"closedSprints\":[{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/23\",\"state\":\"closed\",\"name\":\"sprint 1\",\"startDate\":\"2015-04-11T15:22:00.000+10:00\",\"endDate\":\"2015-04-20T01:22:00.000+10:00\",\"completeDate\":\"2015-04-20T11:04:00.000+10:00\",\"goal\":\"sprint 1 goal\"}],\"description\":\"example bug report\",\"project\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/project/EX\",\"id\":\"10000\",\"key\":\"EX\",\"name\":\"Example\",\"avatarUrls\":{\"48x48\":\"http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000\",\"24x24\":\"http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000\",\"16x16\":\"http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000\",\"32x32\":\"http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000\"},\"projectCategory\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000\",\"id\":\"10000\",\"name\":\"FIRST\",\"description\":\"First Project Category\"},\"simplified\":false,\"style\":\"classic\"},\"comment\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000\",\"id\":\"10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"body\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.\"}]}]},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"created\":\"2019-07-22T05:46:06.698+0000\",\"updated\":\"2019-07-22T05:46:06.699+0000\",\"visibility\":{\"type\":\"role\",\"value\":\"Administrators\"}}],\"epic\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/epic/23\",\"name\":\"epic 1\",\"summary\":\"epic 1 summary\",\"color\":{\"key\":\"color_4\"},\"done\":true},\"worklog\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"comment\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"I did some work here.\"}]}]},\"updated\":\"2019-07-22T05:46:06.706+0000\",\"visibility\":{\"type\":\"group\",\"value\":\"jira-developers\"},\"started\":\"2019-07-22T05:46:06.706+0000\",\"timeSpent\":\"3h 20m\",\"timeSpentSeconds\":12000,\"id\":\"100028\",\"issueId\":\"10002\"}],\"updated\":1,\"timetracking\":{\"originalEstimate\":\"10m\",\"remainingEstimate\":\"3m\",\"timeSpent\":\"6m\",\"originalEstimateSeconds\":600,\"remainingEstimateSeconds\":200,\"timeSpentSeconds\":400}}}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned in these cases:\n\n* the issue does not exist\n* the user does not have permission to view issue" } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/issue/{issueIdOrKey}/estimation": { "get": { "tags": [ "Issue" ], "summary": "Get issue estimation for board", "description": "Returns the estimation of the issue and a fieldId of the field that is used for it. `boardId` param is required. This param determines which field will be updated on a issue.\n\nOriginal time internally stores and returns the estimation as a number of seconds.\n\nThe field used for estimation on the given board can be obtained from [board configuration resource](#agile/1.0/board-getConfiguration). More information about the field are returned by [edit meta resource](#api-rest-api--issue-getEditIssueMeta) or [field resource](#api-rest-api--field-get).", "operationId": "com.atlassian.greenhopper.api.rest.IssueResource.getIssueEstimationForBoard_get", "parameters": [ { "name": "issueIdOrKey", "in": "path", "description": "The ID or key of the requested issue.", "required": true, "schema": { "type": "string" } }, { "name": "boardId", "in": "query", "description": "The ID of the board required to determine which field is used for estimation.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Returns the estimation of the issue and a fieldId of the field that is used for it.", "content": { "application/json": { "examples": { "response": { "value": "{\"fieldId\":\"customfield_12532\",\"value\":\"8.0\"}" } } } } }, "400": { "description": "Returned if the boardId was not provided, field does not exists or value was in wrong format." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if user does not a have valid license or does not have permission to edit issue." }, "404": { "description": "Returned in these cases:\n\n* the issue does not exist\n* the user does not have permission to view issue\n* the board does not exist\n* the user does not have permission to view board\n* the issue does not belong to the board" } }, "deprecated": false, "x-atlassian-connect-scope": "READ" }, "put": { "tags": [ "Issue" ], "summary": "Estimate issue for board", "description": "Updates the estimation of the issue. boardId param is required. This param determines which field will be updated on a issue.\n\nNote that this resource changes the estimation field of the issue regardless of appearance the field on the screen.\n\nOriginal time tracking estimation field accepts estimation in formats like \"1w\", \"2d\", \"3h\", \"20m\" or number which represent number of minutes. However, internally the field stores and returns the estimation as a number of seconds.\n\nThe field used for estimation on the given board can be obtained from [board configuration resource](#agile/1.0/board-getConfiguration). More information about the field are returned by [edit meta resource](#api-rest-api--issue-issueIdOrKey-editmeta-get) or [field resource](#api-rest-api--field-get).", "operationId": "com.atlassian.greenhopper.api.rest.IssueResource.estimateIssueForBoard_put", "parameters": [ { "name": "issueIdOrKey", "in": "path", "description": "The ID or key of the requested issue.", "required": true, "schema": { "type": "string" } }, { "name": "boardId", "in": "query", "description": "The ID of the board required to determine which field is used for estimation.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Returns the estimation of the issue and a fieldId of the field that is used for it.", "content": { "application/json": { "examples": { "response": { "value": "{\"fieldId\":\"customfield_12532\",\"value\":\"8.0\"}" } } } } }, "400": { "description": "Returned if the boardId was not provided, field does not exists or value was in wrong format." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if user does not a have valid license or does not have permission to edit issue." }, "404": { "description": "Returned in these cases:\n\n* the issue does not exist\n* the user does not have permission to view issue\n* the board does not exist\n* the user does not have permission to view board\n* the issue does not belong to the board" } }, "deprecated": false, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" } } }, "examples": { "x-example": { "summary": "Example", "description": "This example was copied over from Swagger V2 into this OAS 3.0 file.", "value": { "value": "8.0" } } } } }, "description": "bean that contains value of a new estimation.", "required": true }, "x-atlassian-connect-scope": "WRITE" } }, "/agile/1.0/sprint": { "post": { "tags": [ "Sprint" ], "summary": "Create sprint", "description": "Creates a future sprint. Sprint name and origin board id are required. Start date, end date, and goal are optional.\n\nNote, the sprint name is trimmed.", "operationId": "com.atlassian.greenhopper.api.rest.SprintResource.createSprint_post", "responses": { "201": { "description": "Created sprint", "content": { "application/json": { "examples": { "response": { "value": "{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/23\",\"state\":\"future\",\"name\":\"sprint 1\",\"startDate\":\"2015-04-11T15:22:00.000+10:00\",\"endDate\":\"2015-04-20T01:22:00.000+10:00\",\"originBoardId\":5,\"goal\":\"sprint 1 goal\"}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if the board does not exist or the user does not have permission to view it." } }, "deprecated": false, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "originBoardId": { "type": "integer", "format": "int64" }, "goal": { "type": "string" } } }, "examples": { "x-example": { "summary": "Example", "description": "This example was copied over from Swagger V2 into this OAS 3.0 file.", "value": { "name": "sprint 1", "startDate": "2015-04-11T15:22:00.000+10:00", "endDate": "2015-04-20T01:22:00.000+10:00", "originBoardId": 5, "goal": "sprint 1 goal" } } } } }, "required": true }, "x-atlassian-connect-scope": "WRITE" } }, "/agile/1.0/sprint/{sprintId}": { "get": { "tags": [ "Sprint" ], "summary": "Get sprint", "description": "Returns the sprint for a given sprint ID. The sprint will only be returned if the user can view the board that the sprint was created on, or view at least one of the issues in the sprint.", "operationId": "com.atlassian.greenhopper.api.rest.SprintResource.getSprint_get", "parameters": [ { "name": "sprintId", "in": "path", "description": "The ID of the requested sprint.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Returns the requested sprint.", "content": { "application/json": { "examples": { "response": { "value": "{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/23\",\"state\":\"closed\",\"name\":\"sprint 1\",\"startDate\":\"2015-04-11T15:22:00.000+10:00\",\"endDate\":\"2015-04-20T01:22:00.000+10:00\",\"completeDate\":\"2015-04-20T11:04:00.000+10:00\",\"originBoardId\":5,\"goal\":\"sprint 1 goal\"}" } } } } }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if the sprint does not exist or the user does not have permission to view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" }, "post": { "tags": [ "Sprint" ], "summary": "Partially update sprint", "description": "Performs a partial update of a sprint. A partial update means that fields not present in the request JSON will not be updated.\n\nNotes:\n\n* Sprints that are in a closed state cannot be updated.\n* A sprint can be started by updating the state to 'active'. This requires the sprint to be in the 'future' state and have a startDate and endDate set.\n* A sprint can be completed by updating the state to 'closed'. This action requires the sprint to be in the 'active' state. This sets the completeDate to the time of the request.\n* Other changes to state are not allowed.\n* The completeDate field cannot be updated manually.", "operationId": "com.atlassian.greenhopper.api.rest.SprintResource.partiallyUpdateSprint_post", "parameters": [ { "name": "sprintId", "in": "path", "description": "The ID of the sprint to update.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Updated sprint", "content": { "application/json": { "examples": { "response": { "value": "{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/23\",\"state\":\"closed\",\"name\":\"sprint 1\",\"startDate\":\"2015-04-11T15:22:00.000+10:00\",\"endDate\":\"2015-04-20T01:22:00.000+10:00\",\"completeDate\":\"2015-04-20T11:04:00.000+10:00\",\"originBoardId\":5,\"goal\":\"sprint 1 goal\"}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if the sprint does not exist." } }, "deprecated": false, "requestBody": { "$ref": "#/components/requestBodies/com.atlassian.greenhopper.api.rest.SprintResource.partiallyUpdateSprint_postSprintbean" }, "x-atlassian-connect-scope": "WRITE" }, "put": { "tags": [ "Sprint" ], "summary": "Update sprint", "description": "Performs a full update of a sprint. A full update means that the result will be exactly the same as the request body. Any fields not present in the request JSON will be set to null.\n\nNotes:\n\n* Sprints that are in a closed state cannot be updated.\n* A sprint can be started by updating the state to 'active'. This requires the sprint to be in the 'future' state and have a startDate and endDate set.\n* A sprint can be completed by updating the state to 'closed'. This action requires the sprint to be in the 'active' state. This sets the completeDate to the time of the request.\n* Other changes to state are not allowed.\n* The completeDate field cannot be updated manually.", "operationId": "com.atlassian.greenhopper.api.rest.SprintResource.updateSprint_put", "parameters": [ { "name": "sprintId", "in": "path", "description": "the ID of the sprint to update.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Updated sprint", "content": { "application/json": { "examples": { "response": { "value": "{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/23\",\"state\":\"closed\",\"name\":\"sprint 1\",\"startDate\":\"2015-04-11T15:22:00.000+10:00\",\"endDate\":\"2015-04-20T01:22:00.000+10:00\",\"completeDate\":\"2015-04-20T11:04:00.000+10:00\",\"originBoardId\":5,\"goal\":\"sprint 1 goal\"}" } } } } }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if the sprint does not exist." } }, "deprecated": false, "requestBody": { "$ref": "#/components/requestBodies/com.atlassian.greenhopper.api.rest.SprintResource.partiallyUpdateSprint_postSprintbean" }, "x-atlassian-connect-scope": "WRITE" }, "delete": { "tags": [ "Sprint" ], "summary": "Delete sprint", "description": "Deletes a sprint. Once a sprint is deleted, all open issues in the sprint will be moved to the backlog.", "operationId": "com.atlassian.greenhopper.api.rest.SprintResource.deleteSprint_delete", "parameters": [ { "name": "sprintId", "in": "path", "description": "The ID of the sprint to delete.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Returned if the sprint was deleted successfully" }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license or does not have permission to delete sprints." }, "404": { "description": "Returned if the sprint does not exist." } }, "deprecated": false, "x-atlassian-connect-scope": "DELETE" } }, "/agile/1.0/sprint/{sprintId}/issue": { "get": { "tags": [ "Sprint" ], "summary": "Get issues for sprint", "description": "Returns all issues in a sprint, for a given sprint ID. This only includes issues that the user has permission to view. By default, the returned issues are ordered by rank.", "operationId": "com.atlassian.greenhopper.api.rest.SprintResource.getIssuesForSprint_get", "parameters": [ { "name": "sprintId", "in": "path", "description": "The ID of the sprint that contains the requested issues.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "startAt", "in": "query", "description": "The starting index of the returned issues. Base index: 0. See the 'Pagination' section at the top of this page for more details.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxResults", "in": "query", "description": "The maximum number of issues to return per page. Default: 50. See the 'Pagination' section at the top of this page for more details. Note, the total number of issues returned is limited by the property 'jira.search.views.default.max' in your Jira instance. If you exceed this limit, your results will be truncated.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "jql", "in": "query", "description": "Filters results using a JQL query. If you define an order in your JQL query, it will override the default order of the returned issues. \nNote that `username` and `userkey` have been deprecated as search terms for this parameter. See the [migration guide](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. Use `accountId` instead.", "required": false, "schema": { "type": "string" } }, { "name": "validateQuery", "in": "query", "description": "Specifies whether to validate the JQL query or not. Default: true.", "required": false, "schema": { "type": "boolean" } }, { "name": "fields", "in": "query", "description": "The list of fields to return for each issue. By default, all navigable and Agile fields are returned.", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "expand", "in": "query", "description": "A comma-separated list of the parameters to expand.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the requested issues, at the specified page of the results.", "content": { "application/json": { "examples": { "response": { "value": "{\"expand\":\"\",\"id\":\"10001\",\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/board/92/issue/10001\",\"key\":\"HSP-1\",\"fields\":{\"flagged\":true,\"sprint\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/13\",\"state\":\"future\",\"name\":\"sprint 2\",\"goal\":\"sprint 2 goal\"},\"closedSprints\":[{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/sprint/23\",\"state\":\"closed\",\"name\":\"sprint 1\",\"startDate\":\"2015-04-11T15:22:00.000+10:00\",\"endDate\":\"2015-04-20T01:22:00.000+10:00\",\"completeDate\":\"2015-04-20T11:04:00.000+10:00\",\"goal\":\"sprint 1 goal\"}],\"description\":\"example bug report\",\"project\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/project/EX\",\"id\":\"10000\",\"key\":\"EX\",\"name\":\"Example\",\"avatarUrls\":{\"48x48\":\"http://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000\",\"24x24\":\"http://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000\",\"16x16\":\"http://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000\",\"32x32\":\"http://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000\"},\"projectCategory\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/projectCategory/10000\",\"id\":\"10000\",\"name\":\"FIRST\",\"description\":\"First Project Category\"},\"simplified\":false,\"style\":\"classic\"},\"comment\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/comment/10000\",\"id\":\"10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"body\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.\"}]}]},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"created\":\"2019-07-22T05:46:06.698+0000\",\"updated\":\"2019-07-22T05:46:06.699+0000\",\"visibility\":{\"type\":\"role\",\"value\":\"Administrators\"}}],\"epic\":{\"id\":37,\"self\":\"http://your-domain.atlassian.net/rest/agile/1.0/epic/23\",\"name\":\"epic 1\",\"summary\":\"epic 1 summary\",\"color\":{\"key\":\"color_4\"},\"done\":true},\"worklog\":[{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/issue/10010/worklog/10000\",\"author\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"updateAuthor\":{\"self\":\"http://your-domain.atlassian.net/rest/api/~ver~/user?accountId=99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"accountId\":\"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e\",\"displayName\":\"Mia Krystof\",\"active\":false},\"comment\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"I did some work here.\"}]}]},\"updated\":\"2019-07-22T05:46:06.706+0000\",\"visibility\":{\"type\":\"group\",\"value\":\"jira-developers\"},\"started\":\"2019-07-22T05:46:06.706+0000\",\"timeSpent\":\"3h 20m\",\"timeSpentSeconds\":12000,\"id\":\"100028\",\"issueId\":\"10002\"}],\"updated\":1,\"timetracking\":{\"originalEstimate\":\"10m\",\"remainingEstimate\":\"3m\",\"timeSpent\":\"6m\",\"originalEstimateSeconds\":600,\"remainingEstimateSeconds\":200,\"timeSpentSeconds\":400}}}" } } } } }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license." }, "404": { "description": "Returned if sprint does not exist or the user cannot view it." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" }, "post": { "tags": [ "Sprint" ], "summary": "Move issues to sprint and rank", "description": "Moves issues to a sprint, for a given sprint ID. Issues can only be moved to open or active sprints. The maximum number of issues that can be moved in one operation is 50.", "operationId": "com.atlassian.greenhopper.api.rest.SprintResource.moveIssuesToSprintAndRank_post", "parameters": [ { "name": "sprintId", "in": "path", "description": "The ID of the sprint that you want to assign issues to.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Empty response is returned if operation was successful." }, "400": { "description": "Returned if the request is invalid." }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license or does not have permission to assign issues." }, "404": { "description": "Returned if the sprint does not exist or the user does not have permission to view it." } }, "deprecated": false, "requestBody": { "$ref": "#/components/requestBodies/com.atlassian.greenhopper.api.rest.BacklogResource.moveIssuesToBacklogForBoard_postIssuerankrequestbean" }, "x-atlassian-connect-scope": "WRITE" } }, "/agile/1.0/sprint/{sprintId}/properties": { "get": { "tags": [ "Sprint" ], "summary": "Get properties keys", "description": "Returns the keys of all properties for the sprint identified by the id. The user who retrieves the property keys is required to have permissions to view the sprint.", "operationId": "com.atlassian.greenhopper.api.rest.SprintPropertyResource.getPropertiesKeys_get", "parameters": [ { "name": "sprintId", "in": "path", "description": "the ID of the sprint from which property keys will be returned.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the sprint with given id exists." }, "400": { "description": "Returned if the sprintId is invalid (negative or not a number)." }, "401": { "description": "Returned if the calling user is not authenticated." }, "403": { "description": "Returned if the calling user does not have permission to view the sprint." }, "404": { "description": "Returned if the sprint with given id does not exist." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" } }, "/agile/1.0/sprint/{sprintId}/properties/{propertyKey}": { "get": { "tags": [ "Sprint" ], "summary": "Get property", "description": "Returns the value of the property with a given key from the sprint identified by the provided id. The user who retrieves the property is required to have permissions to view the sprint.", "operationId": "com.atlassian.greenhopper.api.rest.SprintPropertyResource.getProperty_get", "parameters": [ { "name": "sprintId", "in": "path", "description": "the ID of the sprint from which the property will be returned.", "required": true, "schema": { "type": "string" } }, { "name": "propertyKey", "in": "path", "description": "the key of the property to return.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the sprint exists and the property was found." }, "400": { "description": "Returned if the sprintId is invalid (negative or not a number)." }, "401": { "description": "Returned if the calling user is not authenticated." }, "403": { "description": "Returned if the calling user does not have permission to view the sprint." }, "404": { "description": "Returned if the sprint with a given id does not exist or if the property with given key is not found." } }, "deprecated": false, "x-atlassian-connect-scope": "READ" }, "put": { "tags": [ "Sprint" ], "summary": "Set property", "description": "Sets the value of the specified sprint's property.\n\nYou can use this resource to store a custom data against the sprint identified by the id. The user who stores the data is required to have permissions to modify the sprint.", "operationId": "com.atlassian.greenhopper.api.rest.SprintPropertyResource.setProperty_put", "parameters": [ { "name": "sprintId", "in": "path", "description": "the ID of the sprint on which the property will be set.", "required": true, "schema": { "type": "string" } }, { "name": "propertyKey", "in": "path", "description": "the key of the sprint's property. The maximum length of the key is 255 bytes.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the sprint property is successfully updated." }, "201": { "description": "Returned if the sprint property is successfully created." }, "400": { "description": "Returned if the sprintId is invalid (negative or not a number)." }, "401": { "description": "Returned if the calling user is not authenticated." }, "403": { "description": "Returned if the calling user does not have permission to edit the sprint" }, "404": { "description": "Returned if the sprint with given id does not exist." } }, "deprecated": false, "x-atlassian-connect-scope": "WRITE" }, "delete": { "tags": [ "Sprint" ], "summary": "Delete property", "description": "Removes the property from the sprint identified by the id. Ths user removing the property is required to have permissions to modify the sprint.", "operationId": "com.atlassian.greenhopper.api.rest.SprintPropertyResource.deleteProperty_delete", "parameters": [ { "name": "sprintId", "in": "path", "description": "the ID of the sprint from which the property will be removed.", "required": true, "schema": { "type": "string" } }, { "name": "propertyKey", "in": "path", "description": "the key of the property to remove.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Returned if the sprint property was removed successfully." }, "400": { "description": "Returned if the sprintId is invalid (negative or not a number)." }, "401": { "description": "Returned if the calling user is not authenticated." }, "403": { "description": "Returned if the calling user does not have permission to modify the sprint." }, "404": { "description": "Returned if the sprint with given id does not exist or if the property with given key is not found." } }, "deprecated": false, "x-atlassian-connect-scope": "DELETE" } }, "/agile/1.0/sprint/{sprintId}/swap": { "post": { "tags": [ "Sprint" ], "summary": "Swap sprint", "description": "Swap the position of the sprint with the second sprint.", "operationId": "com.atlassian.greenhopper.api.rest.SprintResource.swapSprint_post", "parameters": [ { "name": "sprintId", "in": "path", "description": "The ID of the sprint to swap.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Returned if the sprint swap was performed successfully" }, "401": { "description": "Returned if the user is not logged in." }, "403": { "description": "Returned if the user does not a have valid license or does not have permission to at least one sprint." }, "404": { "description": "Returned if at least one sprint does not exist or user does not have permission to view to at least one sprint." } }, "deprecated": false, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sprintToSwapWith": { "type": "integer", "format": "int64" } } }, "examples": { "x-example": { "summary": "Example", "description": "This example was copied over from Swagger V2 into this OAS 3.0 file.", "value": { "sprintToSwapWith": 3 } } } } }, "required": true }, "x-atlassian-connect-scope": "WRITE" } }, "/devinfo/0.10/bulk": { "post": { "tags": [ "Development Information" ], "summary": "Store development information", "description": "Stores development information provided in the request to make it available when viewing issues in JIRA. Existing repository and entity data for the same ID will be replaced if the updateSequenceId of existing data is less than the incoming data. Submissions are performed asynchronously. Submitted data will eventually be available in Jira; most updates are available within a short period of time, but may take some time during peak load and/or maintenance times.", "operationId": "storeDevelopmentInformation", "parameters": [ { "name": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.", "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 JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the jiraDevelopmentTool module, or the app does not define the 'WRITE' scope" }, "413": { "description": "Data is too large. Submit fewer devinfo entities in each payload.", "content": { "application/json": { "schema": { "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" } } }, "description": "Request object for development information push operations, entities are grouped by repository" } } }, "description": "Request object, which contains development information", "required": true }, "x-atlassian-connect-scope": "WRITE" } }, "/devinfo/0.10/repository/{repositoryId}": { "get": { "tags": [ "Development Information" ], "summary": "Get repository", "description": "For the specified repository ID, retrieves the repository and the most recent 400 development information entities. The result will be what is currently stored, ignoring any pending updates or deletes.", "operationId": "getRepository", "parameters": [ { "name": "repositoryId", "in": "path", "description": "The ID of repository to fetch", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.", "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 JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the jiraDevelopmentTool module, or the app does not define the 'READ' scope" }, "404": { "description": "No data found for the given repository ID." }, "429": { "description": "API rate limit has been exceeded." }, "500": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "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." } }, "x-atlassian-connect-scope": "READ" }, "delete": { "tags": [ "Development Information" ], "summary": "Delete repository", "description": "Deletes the repository data stored by the given ID and all related development information entities. Deletion is performed asynchronously.", "operationId": "deleteRepository", "parameters": [ { "name": "repositoryId", "in": "path", "description": "The ID of repository to delete", "required": true, "schema": { "type": "string" } }, { "name": "_updateSequenceId", "in": "query", "description": "An optional property to use to control deletion. Only stored data with an updateSequenceId less than or equal to that provided will be deleted. This can be used to help ensure submit/delete requests are applied correctly if they are issued close together.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Delete request has been accepted. Data will eventually be removed from Jira if it exists." }, "401": { "description": "Missing a JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the jiraDevelopmentTool module, or the app does not define the 'DELETE' scope" }, "429": { "description": "API rate limit has been exceeded." }, "500": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "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." } }, "x-atlassian-connect-scope": "DELETE" } }, "/devinfo/0.10/bulkByProperties": { "delete": { "tags": [ "Development Information" ], "summary": "Delete development information by properties", "description": "Deletes development information entities which have all the provided properties. 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": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.", "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 JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the jiraDevelopmentTool module, or the app does not define the 'DELETE' scope" }, "429": { "description": "API rate limit has been exceeded." }, "500": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "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." } }, "x-atlassian-connect-scope": "DELETE" } }, "/devinfo/0.10/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": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.", "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 JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the jiraDevelopmentTool module, or the app does not define the 'READ' scope" }, "429": { "description": "API rate limit has been exceeded." }, "500": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "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." } }, "x-atlassian-connect-scope": "READ" } }, "/devinfo/0.10/repository/{repositoryId}/{entityType}/{entityId}": { "delete": { "tags": [ "Development Information" ], "summary": "Delete development information entity", "description": "Deletes particular development information entity. Deletion is performed asynchronously.", "operationId": "deleteEntity", "parameters": [ { "name": "repositoryId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entityType", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "commit", "branch", "pull_request" ] } }, { "name": "entityId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "_updateSequenceId", "in": "query", "description": "An optional property to use to control deletion. Only stored data with an updateSequenceId less than or equal to that provided will be deleted. This can be used to help ensure submit/delete requests are applied correctly if they are issued close together.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to the provider app installed in Jira. If the JWT token corresponds to an app that does not define the jiraDevelopmentTool module it will be rejected with a 403. See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Delete request has been accepted. Data will eventually be removed from Jira if it exists." }, "400": { "description": "Wrong entity type specified", "content": { "application/json": { "schema": { "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 JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the jiraDevelopmentTool module, or the app does not define the 'DELETE' scope" }, "429": { "description": "API rate limit has been exceeded." }, "500": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "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." } }, "x-atlassian-connect-scope": "DELETE" } }, "/featureflags/0.1/bulk": { "post": { "operationId": "submitFeatureFlags", "summary": "Submit Feature Flag data", "tags": [ "Feature Flags" ], "description": "Update / insert Feature Flag data. Feature Flags are identified by their ID, and existing Feature Flag data for the same ID will be replaced if it exists and 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. The getFeatureFlagById operation can be used to confirm that data has been stored successfully (if needed). In the case of multiple Feature Flags being submitted in one request, each is validated individually prior to submission. Details of which Feature Flags failed submission (if any) are available in the response object. Only apps that define the Feature Flags module can access this resource. This resource requires the 'WRITE' scope.", "responses": { "202": { "description": "Submission accepted. Each submitted Feature Flag that is of a valid format will be eventually available in Jira. Details of which Feature Flags were submitted and which failed submission (due to data format problems etc.) are available in the response object.", "content": { "application/json": { "schema": { "description": "The result of a successful submitFeatureFlags request.", "properties": { "acceptedFeatureFlags": { "description": "The IDs of Feature Flags that have been accepted for submission. A Feature Flag may be rejected if it was only associated with unknown issue keys. Note that a Feature Flag that isn't updated due to it's updateSequenceId being out of order is not considered a failed submission.", "type": "array", "items": { "type": "string" }, "example": [ "111-222-333", "444-555-666" ] }, "failedFeatureFlags": { "description": "Details of Feature Flags that have not been accepted for submission, usually due to a problem with the request data. The object (if present) will be keyed by Feature Flag ID and include any errors associated with that Feature Flag that have prevented it being submitted.", "type": "object", "additionalProperties": { "type": "array", "items": { "description": "A message supplied in the case of an error.", "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." } } } } }, "unknownIssueKeys": { "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 Feature Flag has been associated with issue keys other than those in this array it will still be stored against those valid keys. If a Feature Flag was only associated with issue keys deemed to be invalid it won't be persisted.", "type": "array", "items": { "description": "An issue key that references an issue in Jira.\n", "type": "string", "pattern": "\\w{1,255}-\\d{1,255}", "example": "ISSUE-123" } } } } } } }, "400": { "description": "Request has incorrect format. Note that in the case of an individual Feature Flag 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 Feature Flag will be contained in the response object.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } }, "401": { "description": "Missing a JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the Feature Flags module, or the app does not define the 'WRITE' scope." }, "413": { "description": "Data is too large. Submit fewer Feature Flags in each payload.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } }, "429": { "description": "API rate limit has been exceeded." }, "503": { "description": "Service is unavailable due to maintenance or other reasons." }, "default": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "The payload used to submit (update / insert) Feature Flag data.", "required": [ "flags" ], "properties": { "properties": { "description": "Arbitrary properties to tag the submitted Feature Flags with. These properties can be used for delete operations to e.g. clean up all Feature Flags 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 Feature Flag data. They are not intended for use as metadata to associate with a Feature Flag. Internally they are stored as a hash so that personal information etc. is never stored within Jira.", "type": "object", "additionalProperties": { "type": "string", "maxLength": 255 }, "example": { "accountId": "account-234", "projectId": "project-123" } }, "flags": { "description": "A list of Feature Flags to submit to Jira. Each Feature Flag may be associated with 1 or more Jira issue keys, and will be associated with any properties included in this request.", "type": "array", "items": { "description": "Data related to a single Feature Flag, across any Environment that the flag is present in.\n", "required": [ "id", "key", "issueKeys", "summary", "details", "updateSequenceId" ], "properties": { "schemaVersion": { "description": "The FeatureFlagData schema version used for this flag data. \n\nPlaceholder to support potential schema changes in the future.\n", "type": "string", "enum": [ "1.0" ], "default": "1.0", "example": "1.0" }, "id": { "description": "The identifier for the Feature Flag. Must be unique for a given Provider.\n", "type": "string", "maxLength": 255, "example": "111-222-333" }, "key": { "description": "The identifier that users would use to reference the Feature Flag in their source code etc.\n\nWill be made available via the UI for users to copy into their source code etc.\n", "type": "string", "maxLength": 255, "example": "my-awesome-feature" }, "updateSequenceId": { "description": "An ID used to apply an ordering to updates for this Feature Flag in the case of out-of-order receipt of update requests.\n\nThis 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 Feature Flag and increment that on each update to Jira).\n\nUpdates for a Feature Flag that are received with an updateSqeuenceId lower than what is currently stored will be ignored.\n", "type": "integer", "format": "int64", "example": 1523494301448 }, "displayName": { "description": "The human-readable name for the Feature Flag. Will be shown in the UI.\n\nIf not provided, will use the ID for display.\n", "type": "string", "maxLength": 255, "example": "Enable awesome feature" }, "issueKeys": { "description": "The Jira issue keys to associate the Feature Flag information with.\n", "type": "array", "items": { "description": "An issue key that references an issue in Jira.\n", "type": "string", "pattern": "\\w{1,255}-\\d{1,255}", "example": "ISSUE-123" }, "minItems": 1, "maxItems": 100 }, "summary": { "description": "Summary information for this Feature Flag.\n\nProviders may elect to provide information from a specific environment, or they may choose to 'roll up' information from across multiple environments - whatever makes most sense in the Provider system.\n\nThis is the summary information that will be presented to the user on e.g. the issue screen.\n", "required": [ "status", "lastUpdated" ], "properties": { "url": { "description": "A URL users can use to link to a summary view of this flag, if appropriate. \n\nThis could be any location that makes sense in the Provider system (e.g. if the summary information comes from a specific environment, it might make sense to link the user to the flag in that environment).\n", "type": "string", "format": "URI", "maxLength": 2000, "example": "https://example.com/project/feature-123/summary" }, "status": { "description": "The Feature Flag status to present to the user as a summary of the state of the Feature Flag.\n", "required": [ "enabled" ], "properties": { "enabled": { "description": "Whether the Feature Flag is enabled in the given environment (or in summary). \n\nEnabled may imply a partial rollout, which can be described using the 'rollout' field.\n", "type": "boolean" }, "defaultValue": { "description": "The value served by this Feature Flag when it is disabled. This could be the actual value or an alias, as appropriate.\n\nThis value may be presented to the user in the UI.\n", "type": "string", "maxLength": 255, "example": "Disabled" }, "rollout": { "description": "Details of the rollout for the Feature Flag in an environment (or in summary).\n\nIf 'enabled' is false, this field will be ignored. If 'enabled' is true, this field should be provided to describe the rollout. If 'enabled' is true and this field is missing, rollout will be assumed to be 100%.\n", "properties": { "percentage": { "description": "If the Feature Flag rollout is a simple percentage rollout\n", "type": "number", "minimum": 0 }, "text": { "description": "A text status to display that represents the rollout. This could be e.g. a named cohort.\n", "type": "string", "maxLength": 255 }, "rules": { "description": "A count of the number of rules active for this Feature Flag in an environment.\n", "type": "integer", "minimum": 0 } }, "example": { "percentage": 80 } } } }, "lastUpdated": { "description": "The last-updated timestamp to present to the user as a summary of the state of the Feature Flag.\n\nProviders may choose to supply the last-updated timestamp from a specific environment, or the 'most recent' last-updated timestamp across all environments - whatever makes sense in the Provider system.\n\nExpected format is an RFC3339 formated string.\n", "type": "string", "format": "date-time", "example": "2018-01-20T23:27:25+00:00" } } }, "details": { "description": "Detail information for this Feature Flag.\n\nThis may be information for each environment the Feature Flag is defined in or a selection of environments made by the user, as appropriate.\n", "type": "array", "items": { "description": "Details of a Feature Flag for a single environment.", "required": [ "url", "lastUpdated", "environment", "status" ], "properties": { "url": { "description": "A URL users can use to link to this Feature Flag, in this environment.\n", "type": "string", "format": "URI", "maxLength": 2000, "example": "https://example.com/project/feature-123/production" }, "lastUpdated": { "description": "The last-updated timestamp for this Feature Flag, in this environment.\n\nExpected format is an RFC3339 formated string.\n", "type": "string", "format": "date-time", "example": "2018-01-20T23:27:25+00:00" }, "environment": { "description": "The environment the details of the Feature Flag are for.\n", "required": [ "name" ], "properties": { "name": { "description": "The name of the environment.", "type": "string", "maxLength": 255 }, "type": { "description": "The 'type' or 'category' of environment this environment belongs to.", "type": "string", "enum": [ "development", "testing", "staging", "production" ] } }, "example": { "name": "prod-us-west", "type": "production" } }, "status": { "description": "The status of the Feature Flag in the environment.\n", "required": [ "enabled" ], "properties": { "enabled": { "description": "Whether the Feature Flag is enabled in the given environment (or in summary). \n\nEnabled may imply a partial rollout, which can be described using the 'rollout' field.\n", "type": "boolean" }, "defaultValue": { "description": "The value served by this Feature Flag when it is disabled. This could be the actual value or an alias, as appropriate.\n\nThis value may be presented to the user in the UI.\n", "type": "string", "maxLength": 255, "example": "Disabled" }, "rollout": { "description": "Details of the rollout for the Feature Flag in an environment (or in summary).\n\nIf 'enabled' is false, this field will be ignored. If 'enabled' is true, this field should be provided to describe the rollout. If 'enabled' is true and this field is missing, rollout will be assumed to be 100%.\n", "properties": { "percentage": { "description": "If the Feature Flag rollout is a simple percentage rollout\n", "type": "number", "minimum": 0 }, "text": { "description": "A text status to display that represents the rollout. This could be e.g. a named cohort.\n", "type": "string", "maxLength": 255 }, "rules": { "description": "A count of the number of rules active for this Feature Flag in an environment.\n", "type": "integer", "minimum": 0 } }, "example": { "percentage": 80 } } } } } }, "minItems": 1 } } }, "minItems": 1 } } } } }, "description": "Feature Flag data to submit.", "required": true }, "x-atlassian-connect-scope": "WRITE" }, "parameters": [ { "name": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.\n\nIf the JWT token corresponds to an app that does not define Feature Flags module it will be rejected with a 403.\n\nSee https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.\n", "required": true, "schema": { "type": "string", "pattern": "JWT \\S+" } } ] }, "/featureflags/0.1/bulkByProperties": { "delete": { "operationId": "deleteFeatureFlagsByProperty", "summary": "Delete Feature Flags by Property", "tags": [ "Feature Flags" ], "description": "Bulk delete all Feature Flags that match the given request. In addition to the optional `updateSequenceId`, one or more query params must be supplied to specify Properties to delete by. If more than one Property is provided, data will be deleted that matches ALL of the Properties (e.g. treated as an AND). See the documentation for the submitFeatureFlags operation for more details. e.g. DELETE /bulkByProperties?accountId=account-123&createdBy=user-456 Deletion is performed asynchronously. The getFeatureFlagById operation can be used to confirm that data has been deleted successfully (if needed). Only apps that define the Feature Flags module can access this resource. This resource requires the 'DELETE' scope.", "parameters": [ { "name": "_updateSequenceId", "in": "query", "description": "An optional `updateSequenceId` 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 help ensure submit/delete requests are applied correctly if issued close together. If not provided, all stored data that matches the request will be deleted.", "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 (e.g. missing at least one Property param).", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } }, "401": { "description": "Missing a JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the Feature Flags module, or the app does not define the 'DELETE' scope." }, "429": { "description": "API rate limit has been exceeded." }, "503": { "description": "Service is unavailable due to maintenance or other reasons." }, "default": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } } }, "x-atlassian-connect-scope": "DELETE" }, "parameters": [ { "name": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.\n\nIf the JWT token corresponds to an app that does not define Feature Flags module it will be rejected with a 403.\n\nSee https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.\n", "required": true, "schema": { "type": "string", "pattern": "JWT \\S+" } } ] }, "/featureflags/0.1/flag/{featureFlagId}": { "get": { "operationId": "getFeatureFlagById", "summary": "Get a Feature Flag by ID", "tags": [ "Feature Flags" ], "description": "Retrieve the currently stored Feature Flag data for the given ID. The result will be what is currently stored, ignoring any pending updates or deletes. Only apps that define the Feature Flags module can access this resource. This resource requires the 'READ' scope.", "parameters": [ { "name": "featureFlagId", "in": "path", "description": "The ID of the Feature Flag to fetch.", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "The Feature Flag data currently stored for the given ID.", "content": { "application/json": { "schema": { "description": "Data related to a single Feature Flag, across any Environment that the flag is present in.", "required": [ "id", "key", "issueKeys", "summary", "details", "updateSequenceId" ], "properties": { "schemaVersion": { "description": "The FeatureFlagData schema version used for this flag data. Placeholder to support potential schema changes in the future.", "type": "string", "enum": [ "1.0" ], "default": "1.0", "example": "1.0" }, "id": { "description": "The identifier for the Feature Flag. Must be unique for a given Provider.", "type": "string", "maxLength": 255, "example": "111-222-333" }, "key": { "description": "The identifier that users would use to reference the Feature Flag in their source code etc. Will be made available via the UI for users to copy into their source code etc.", "type": "string", "maxLength": 255, "example": "my-awesome-feature" }, "updateSequenceId": { "description": "An ID used to apply an ordering to updates for this Feature Flag 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 Feature Flag and increment that on each update to Jira). Updates for a Feature Flag that are received with an updateSqeuenceId lower than what is currently stored will be ignored.", "type": "integer", "format": "int64", "example": 1523494301448 }, "displayName": { "description": "The human-readable name for the Feature Flag. Will be shown in the UI. If not provided, will use the ID for display.", "type": "string", "maxLength": 255, "example": "Enable awesome feature" }, "issueKeys": { "description": "The Jira issue keys to associate the Feature Flag information with.", "type": "array", "items": { "description": "An issue key that references an issue in Jira.\n", "type": "string", "pattern": "\\w{1,255}-\\d{1,255}", "example": "ISSUE-123" }, "minItems": 1, "maxItems": 100 }, "summary": { "description": "Summary information for this Feature Flag. Providers may elect to provide information from a specific environment, or they may choose to 'roll up' information from across multiple environments - whatever makes most sense in the Provider system. This is the summary information that will be presented to the user on e.g. the issue screen.", "required": [ "status", "lastUpdated" ], "properties": { "url": { "description": "A URL users can use to link to a summary view of this flag, if appropriate. This could be any location that makes sense in the Provider system (e.g. if the summary information comes from a specific environment, it might make sense to link the user to the flag in that environment).", "type": "string", "format": "URI", "maxLength": 2000, "example": "https://example.com/project/feature-123/summary" }, "status": { "description": "The Feature Flag status to present to the user as a summary of the state of the Feature Flag.", "required": [ "enabled" ], "properties": { "enabled": { "description": "Whether the Feature Flag is enabled in the given environment (or in summary). Enabled may imply a partial rollout, which can be described using the 'rollout' field.", "type": "boolean" }, "defaultValue": { "description": "The value served by this Feature Flag when it is disabled. This could be the actual value or an alias, as appropriate. This value may be presented to the user in the UI.", "type": "string", "maxLength": 255, "example": "Disabled" }, "rollout": { "description": "Details of the rollout for the Feature Flag in an environment (or in summary). If 'enabled' is false, this field will be ignored. If 'enabled' is true, this field should be provided to describe the rollout. If 'enabled' is true and this field is missing, rollout will be assumed to be 100%.", "properties": { "percentage": { "description": "If the Feature Flag rollout is a simple percentage rollout", "type": "number", "minimum": 0 }, "text": { "description": "A text status to display that represents the rollout. This could be e.g. a named cohort.", "type": "string", "maxLength": 255 }, "rules": { "description": "A count of the number of rules active for this Feature Flag in an environment.", "type": "integer", "minimum": 0 } }, "example": { "percentage": 80 } } } }, "lastUpdated": { "description": "The last-updated timestamp to present to the user as a summary of the state of the Feature Flag. Providers may choose to supply the last-updated timestamp from a specific environment, or the 'most recent' last-updated timestamp across all environments - whatever makes sense in the Provider system. Expected format is an RFC3339 formated string.", "type": "string", "format": "date-time", "example": "2018-01-20T23:27:25+00:00" } } }, "details": { "description": "Detail information for this Feature Flag. This may be information for each environment the Feature Flag is defined in or a selection of environments made by the user, as appropriate.", "type": "array", "items": { "description": "Details of a Feature Flag for a single environment.", "required": [ "url", "lastUpdated", "environment", "status" ], "properties": { "url": { "description": "A URL users can use to link to this Feature Flag, in this environment.\n", "type": "string", "format": "URI", "maxLength": 2000, "example": "https://example.com/project/feature-123/production" }, "lastUpdated": { "description": "The last-updated timestamp for this Feature Flag, in this environment.\n\nExpected format is an RFC3339 formated string.\n", "type": "string", "format": "date-time", "example": "2018-01-20T23:27:25+00:00" }, "environment": { "description": "The environment the details of the Feature Flag are for.\n", "required": [ "name" ], "properties": { "name": { "description": "The name of the environment.", "type": "string", "maxLength": 255 }, "type": { "description": "The 'type' or 'category' of environment this environment belongs to.", "type": "string", "enum": [ "development", "testing", "staging", "production" ] } }, "example": { "name": "prod-us-west", "type": "production" } }, "status": { "description": "The status of the Feature Flag in the environment.\n", "required": [ "enabled" ], "properties": { "enabled": { "description": "Whether the Feature Flag is enabled in the given environment (or in summary). \n\nEnabled may imply a partial rollout, which can be described using the 'rollout' field.\n", "type": "boolean" }, "defaultValue": { "description": "The value served by this Feature Flag when it is disabled. This could be the actual value or an alias, as appropriate.\n\nThis value may be presented to the user in the UI.\n", "type": "string", "maxLength": 255, "example": "Disabled" }, "rollout": { "description": "Details of the rollout for the Feature Flag in an environment (or in summary).\n\nIf 'enabled' is false, this field will be ignored. If 'enabled' is true, this field should be provided to describe the rollout. If 'enabled' is true and this field is missing, rollout will be assumed to be 100%.\n", "properties": { "percentage": { "description": "If the Feature Flag rollout is a simple percentage rollout\n", "type": "number", "minimum": 0 }, "text": { "description": "A text status to display that represents the rollout. This could be e.g. a named cohort.\n", "type": "string", "maxLength": 255 }, "rules": { "description": "A count of the number of rules active for this Feature Flag in an environment.\n", "type": "integer", "minimum": 0 } }, "example": { "percentage": 80 } } } } } }, "minItems": 1 } } } } } }, "401": { "description": "Missing a JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the Feature Flags module, or the app does not define the 'READ' scope." }, "404": { "description": "No data found for the given Feature Flag ID." }, "429": { "description": "API rate limit has been exceeded." }, "503": { "description": "Service is unavailable due to maintenance or other reasons." }, "default": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } } }, "x-atlassian-connect-scope": "READ" }, "delete": { "operationId": "deleteFeatureFlagById", "summary": "Delete a Feature Flag by ID", "tags": [ "Feature Flags" ], "description": "Delete the Feature Flag data currently stored for the given ID. Deletion is performed asynchronously. The getFeatureFlagById operation can be used to confirm that data has been deleted successfully (if needed). Only apps that define the Feature Flags module can access this resource. This resource requires the 'DELETE' scope.", "parameters": [ { "name": "featureFlagId", "in": "path", "description": "The ID of the Feature Flag to delete.", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "_updateSequenceId", "in": "query", "description": "An optional `updateSequenceId` 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 help ensure submit/delete requests are applied correctly if issued close together.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "202": { "description": "Delete has been accepted. Data will eventually be removed from Jira if it exists." }, "401": { "description": "Missing a JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the Feature Flags module, or the app does not define the 'DELETE' scope." }, "429": { "description": "API rate limit has been exceeded." }, "503": { "description": "Service is unavailable due to maintenance or other reasons." }, "default": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } } }, "x-atlassian-connect-scope": "DELETE" }, "parameters": [ { "name": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.\n\nIf the JWT token corresponds to an app that does not define Feature Flags module it will be rejected with a 403.\n\nSee https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.\n", "required": true, "schema": { "type": "string", "pattern": "JWT \\S+" } } ] }, "/deployments/0.1/bulk": { "post": { "operationId": "submitDeployments", "summary": "Submit deployment data", "tags": [ "Deployments" ], "description": "Update / insert deployment data. Deployments are identified by the combination of `pipelineId`, `environmentId` and `deploymentSequenceNumber`, and existing deployment data for the same deployment will be replaced if it exists and the `updateSequenceNumber` of existing data is less than the incoming data. Submissions are processed asynchronously. Submitted data will eventually be available in Jira. Most updates are available within a short period of time, but may take some time during peak load and/or maintenance times. The `getDeploymentByKey` operation can be used to confirm that data has been stored successfully (if needed). In the case of multiple deployments being submitted in one request, each is validated individually prior to submission. Details of which deployments failed submission (if any) are available in the response object. Only apps that define the `jiraDeploymentInfoProvider` module can access this resource. This resource requires the 'WRITE' scope.", "responses": { "202": { "description": "Submission accepted. Each submitted deployment that is of a valid format will eventually be available in Jira. Details of which deployments were submitted and which failed submission (due to data format problems etc.) are available in the response object.", "content": { "application/json": { "schema": { "description": "The result of a successful submitDeployments request.", "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`. A deployment may be rejected if it was only associated with unknown issue keys. Note that a deployment that isn't updated due to it's updateSequenceNumber being out of order is not considered a failed submission.", "type": "array", "items": { "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 } } } }, "rejectedDeployments": { "description": "Details of deployments that have not been accepted for submission, usually due to a problem with the request data. The object will contain the deployment key and any errors associated with that deployment that have prevented it being submitted.", "type": "array", "items": { "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": { "description": "The key of the rejected deployment", "type": "object", "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 } } }, "errors": { "description": "The error messages for the rejected deployment", "type": "array", "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } }, "unknownIssueKeys": { "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 deployment has been associated with issue keys other than those in this array it will still be stored against those valid keys. If a deployment was only associated with issue keys deemed to be invalid it won't be persisted.", "type": "array", "items": { "description": "An issue key that references an issue in Jira.\n", "type": "string", "pattern": "\\w{1,255}-\\d{1,255}", "example": "ABC-123" } } } } } } }, "400": { "description": "Request has incorrect format. Note that in the case of an individual deployment having an invalid format (rather than the request as a whole) the response for the request will be a 202 and details of the invalid deployment will be contained in the response object.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } }, "401": { "description": "Missing a JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the `jiraDeploymentInfoProvider` module, or the app does not define the 'WRITE' scope." }, "413": { "description": "Data is too large. Submit fewer deployments in each payload.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } }, "429": { "description": "API rate limit has been exceeded." }, "503": { "description": "Service is unavailable due to maintenance or other reasons." }, "default": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "The payload used to submit (update / insert) deployment data.", "required": [ "deployments" ], "properties": { "properties": { "description": "Arbitrary properties to tag the submitted deployments with. These properties can be used for delete operations to e.g. clean up all deployments 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 deployment data. They are not intended for use as metadata to associate with a deployment. Internally they are stored as a hash so that personal information etc. is never stored within Jira.", "type": "object", "additionalProperties": { "type": "string", "maxLength": 255 }, "maxProperties": 5, "example": { "accountId": "account-234", "projectId": "project-123" } }, "deployments": { "description": "A list of deployments to submit to Jira. Each deployment may be associated with one or more Jira issue keys, and will be associated with any properties included in this request.", "type": "array", "items": { "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": { "description": "An issue key that references an issue in Jira.\n", "type": "string", "pattern": "\\w{1,255}-\\d{1,255}", "example": "ABC-123" }, "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": { "description": "The pipeline that generated this deployment.\n", "type": "object", "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 this deployment is targeting.\n", "type": "object", "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" } } }, "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" } } }, "minItems": 1 } } } } }, "description": "Deployment data to submit.", "required": true }, "x-atlassian-connect-scope": "WRITE" }, "parameters": [ { "name": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.\n\nIf the JWT token corresponds to an app that does not define `jiraDeploymentInfoProvider` module it will be rejected with a 403.\n\nSee https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.\n", "required": true, "schema": { "type": "string", "pattern": "JWT \\S+" } } ] }, "/deployments/0.1/bulkByProperties": { "delete": { "operationId": "deleteDeploymentsByProperty", "summary": "Delete deployments by Property", "tags": [ "Deployments" ], "description": "Bulk delete all deployments that match the given request. In addition to the optional `_updateSequenceNumber`, one or more query params must be supplied to specify the Properties to delete by. If more than one Property is provided, data will be deleted that matches ALL of the Properties (i.e. treated as AND). See the documentation for the `submitDeployments` operation for more details. Example operation: DELETE /bulkByProperties?accountId=account-123&createdBy=user-456 Deletion is performed asynchronously. The `getDeploymentByKey` operation can be used to confirm that data has been deleted successfully (if needed). Only apps that define the `jiraDeploymentInfoProvider` module can access this resource. This resource requires the 'DELETE' scope.", "parameters": [ { "name": "_updateSequenceNumber", "in": "query", "description": "An optional `updateSequenceNumber` to use to control deletion. Only stored data with an `updateSequenceNumber` less than or equal to that provided will be deleted. This can be used help ensure submit/delete requests are applied correctly if issued close together. If not provided, all stored data that matches the request will be deleted.", "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 (e.g. missing at least one Property param).", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } }, "401": { "description": "Missing a JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the `jiraDeploymentInfoProvider` module, or the app does not define the 'DELETE' scope." }, "429": { "description": "API rate limit has been exceeded." }, "503": { "description": "Service is unavailable due to maintenance or other reasons." }, "default": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } } }, "x-atlassian-connect-scope": "DELETE" }, "parameters": [ { "name": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.\n\nIf the JWT token corresponds to an app that does not define `jiraDeploymentInfoProvider` module it will be rejected with a 403.\n\nSee https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.\n", "required": true, "schema": { "type": "string", "pattern": "JWT \\S+" } } ] }, "/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. The result will be what is currently stored, ignoring any pending updates or deletes. Only apps that define the `jiraDeploymentInfoProvider` module can access this resource. This resource requires the 'READ' scope.", "parameters": [ { "name": "pipelineId", "in": "path", "description": "The ID of the deployment's pipeline.", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "environmentId", "in": "path", "description": "The ID of the deployment's environment.", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "deploymentSequenceNumber", "in": "path", "description": "The deployment's deploymentSequenceNumber.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "The deployment data currently stored for the given ID.", "content": { "application/json": { "schema": { "description": "Data related to a specific deployment in a specific environment that the deployment is present in.", "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.", "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.", "type": "integer", "format": "int64", "example": 1 }, "issueKeys": { "description": "The Jira issue keys to associate the deployment information with.", "type": "array", "items": { "description": "An issue key that references an issue in Jira.\n", "type": "string", "pattern": "\\w{1,255}-\\d{1,255}", "example": "ABC-123" }, "minItems": 1, "maxItems": 100 }, "displayName": { "description": "The human-readable name for the deployment. Will be shown in the UI.", "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.", "type": "string", "format": "URI", "maxLength": 2000, "example": "http://mydeployer.com/project1/1111-222-333/prod-east" }, "description": { "description": "A short description of the deployment", "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.", "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.", "type": "string", "maxLength": 255, "example": "Release 2018-01-20_08-47-bc2421a" }, "state": { "description": "The state of the deployment", "type": "string", "enum": [ "unknown", "pending", "in_progress", "cancelled", "failed", "rolled_back", "successful" ], "example": "in_progress" }, "pipeline": { "description": "The pipeline that generated this deployment.", "type": "object", "required": [ "id", "displayName", "url" ], "properties": { "id": { "description": "The identifier of this pipeline, must be unique for the provider.", "type": "string", "maxLength": 255, "example": "e9c906a7-451f-4fa6-ae1a-c389e2e2d87c" }, "displayName": { "description": "The name of the pipeline to present to the user.", "type": "string", "maxLength": 255, "example": "Data Depot Deployment" }, "url": { "description": "A URL users can use to link to this deployment pipeline.", "type": "string", "format": "URI", "maxLength": 2000, "example": "http://mydeployer.com/project1" } } }, "environment": { "description": "The environment that this deployment is targeting.", "type": "object", "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.", "type": "string", "maxLength": 255, "example": "8ec94d72-a4fc-4ac0-b31d-c5a595f373ba" }, "displayName": { "description": "The name of the environment to present to the user.", "type": "string", "maxLength": 255, "example": "US East" }, "type": { "description": "The type of the environment.", "type": "string", "enum": [ "unmapped", "development", "testing", "staging", "production" ], "example": "production" } } }, "schemaVersion": { "description": "The DeploymentData schema version used for this deployment data. Placeholder to support potential schema changes in the future.", "type": "string", "enum": [ "1.0" ], "default": "1.0", "example": "1.0" } } } } } }, "401": { "description": "Missing a JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the `jiraDeploymentInfoProvider` module, or the app does not define the 'READ' scope." }, "404": { "description": "No data found for the given deployment ID." }, "429": { "description": "API rate limit has been exceeded." }, "503": { "description": "Service is unavailable due to maintenance or other reasons." }, "default": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } } }, "x-atlassian-connect-scope": "READ" }, "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. Deletion is performed asynchronously. The `getDeploymentByKey` operation can be used to confirm that data has been deleted successfully (if needed). Only apps that define the `jiraDeploymentInfoProvider` module can access this resource. This resource requires the 'DELETE' scope.", "parameters": [ { "name": "pipelineId", "in": "path", "description": "The ID of the deployment's pipeline.", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "environmentId", "in": "path", "description": "The ID of the deployment's environment.", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "deploymentSequenceNumber", "in": "path", "description": "The deployment's deploymentSequenceNumber.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "_updateSequenceNumber", "in": "query", "description": "An optional `_updateSequenceNumber` to use to control deletion. Only stored data with an `updateSequenceNumber` less than or equal to that provided will be deleted. This can be used help ensure submit/delete requests are applied correctly if issued close together.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "202": { "description": "Delete has been accepted. Data will eventually be removed from Jira if it exists." }, "401": { "description": "Missing a JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the `jiraDeploymentInfoProvider` module, or the app does not define the 'DELETE' scope." }, "429": { "description": "API rate limit has been exceeded." }, "503": { "description": "Service is unavailable due to maintenance or other reasons." }, "default": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "description": "A message supplied in the case of an error.", "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." } } } } } } } }, "x-atlassian-connect-scope": "DELETE" }, "parameters": [ { "name": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.\n\nIf the JWT token corresponds to an app that does not define `jiraDeploymentInfoProvider` module it will be rejected with a 403.\n\nSee https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.\n", "required": true, "schema": { "type": "string", "pattern": "JWT \\S+" } } ] }, "/builds/0.1/bulk": { "post": { "operationId": "submitBuilds", "summary": "Submit build data", "tags": [ "Builds" ], "description": "Update / insert builds data. Builds are identified by the combination of `pipelineId` and `buildNumber`, and existing build data for the same build will be replaced if it exists and the `updateSequenceNumber` of the existing data is less than the incoming data. Submissions are performed asynchronously. Submitted data will eventually be available in Jira; most updates are available within a short period of time, but may take some time during peak load and/or maintenance times. The `getBuildByKey` operation can be used to confirm that data has been stored successfully (if needed). In the case of multiple builds being submitted in one request, each is validated individually prior to submission. Details of which build failed submission (if any) are available in the response object. Only apps that define the `jiraBuildInfoProvider` module can access this resource. This resource requires the 'WRITE' scope.", "responses": { "202": { "description": "Submission accepted. Each submitted build that is of a valid format will be eventually available in Jira. Details of which builds were submitted and which failed submission (due to data format problems etc.) are available in the response object.", "content": { "application/json": { "schema": { "description": "The result of a successful `submitBuilds` request.", "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 `pipelineId` and `buildNumber`. A build may be rejected if it was only associated with unknown issue keys, or if the submitted data for that build does not match the required schema. Note that a build that isn't updated due to it's `updateSequenceNumber` being out of order is not considered a failed submission.", "type": "array", "items": { "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 } } } }, "rejectedBuilds": { "description": "Details of builds that have not been accepted for submission. A build may be rejected if it was only associated with unknown issue keys, or if the submitted data for the build does not match the required schema.", "type": "array", "items": { "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": { "description": "The key of the rejected build", "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 } } }, "errors": { "description": "The error messages for the rejected build", "type": "array", "items": { "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." } } } } } } }, "unknownIssueKeys": { "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 build has been associated with issue keys other than those in this array it will still be stored against those valid keys. If a build was only associated with issue keys deemed to be invalid it won't be persisted.", "type": "array", "items": { "description": "An issue key that references an issue in Jira.\n", "type": "string", "pattern": "\\w{1,255}-\\d{1,255}", "example": "ISSUE-123" } } } } } } }, "400": { "description": "Request has incorrect format. Note that in the case of an individual build having an invalid format (rather than the request as a whole) the response for the request will be a 202 and details of the invalid build will be contained in the response object.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "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." } } } } } } }, "401": { "description": "Missing a JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the `jiraBuildInfoProvider` module, or the app does not define the 'WRITE' scope." }, "413": { "description": "Data is too large. Submit fewer builds in each payload.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "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." } } } } } } }, "429": { "description": "API rate limit has been exceeded." }, "503": { "description": "Service is unavailable due to maintenance or other reasons." }, "default": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "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." } } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "The payload used to submit (update / insert) build data.", "type": "object", "required": [ "builds" ], "properties": { "properties": { "description": "Arbitrary properties to tag the submitted builds with. These properties can be used for delete operations to e.g. clean up all builds associated with an account in the event that the account is removed from your system. Note that these properties will never be returned with build data. They are not intended for use as metadata to associate with a build. Internally they are stored as a hash so that personal information etc. is never stored within Jira. A maximum of 5 properties can be associated with a build.", "type": "object", "additionalProperties": { "type": "string", "maxLength": 255 }, "maxProperties": 5, "example": { "accountId": "account-234", "projectId": "project-123" } }, "builds": { "description": "A list of builds to submit to Jira. Each build may be associated with one or more Jira issue keys, and will be associated with any properties included in this request.", "type": "array", "items": { "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": { "description": "The state of this build\n", "type": "string", "enum": [ "pending", "in_progress", "successful", "failed", "cancelled", "unknown" ], "example": "failed" }, "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": { "description": "An issue key that references an issue in Jira.\n", "type": "string", "pattern": "\\w{1,255}-\\d{1,255}", "example": "ISSUE-123" }, "minItems": 1, "maxItems": 100 }, "testInfo": { "description": "Optional information about tests that were executed during the 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 } } }, "references": { "description": "Optional information that links a build to a commit, branch etc.\n", "type": "array", "items": { "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": { "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" } } }, "ref": { "description": "Details about the ref (branch, tag etc.) 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" } } } } }, "minItems": 1, "maxItems": 5 } } }, "minItems": 1 } } } } }, "description": "Builds data to submit.", "required": true }, "x-atlassian-connect-scope": "WRITE" }, "parameters": [ { "name": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to an app installed in Jira.\n\nIf the JWT token corresponds to an app that does not define `jiraBuildInfoProvider` module it will be rejected with a 403.\n\nSee https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.\n", "required": true, "schema": { "type": "string", "pattern": "JWT \\S+" } } ] }, "/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. In addition to the optional `_updateSequenceNumber`, one or more query params must be supplied to specify Properties to delete by. If more than one Property is provided, data will be deleted that matches ALL of the Properties (e.g. treated as an AND). See the documentation for the `submitBuilds` operation for more details. e.g. DELETE /bulkByProperties?accountId=account-123&repoId=repo-345 Deletion is performed asynchronously. The `getBuildByKey` operation can be used to confirm that data has been deleted successfully (if needed). Only apps that define the `jiraBuildInfoProvider` module can access this resource. This resource requires the 'DELETE' scope.", "parameters": [ { "name": "_updateSequenceNumber", "in": "query", "description": "An optional `updateSequenceNumber` to use to control deletion. Only stored data with an `updateSequenceNumber` less than or equal to that provided will be deleted. This can be used help ensure submit/delete requests are applied correctly if issued close together. If not provided, all stored data that matches the request will be deleted.", "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 (e.g. missing at least one Property param).", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "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." } } } } } } }, "401": { "description": "Missing a JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the `jiraBuildInfoProvider` module, or the app does not define the 'DELETE' scope." }, "429": { "description": "API rate limit has been exceeded." }, "503": { "description": "Service is unavailable due to maintenance or other reasons." }, "default": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "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." } } } } } } } }, "x-atlassian-connect-scope": "DELETE" }, "parameters": [ { "name": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to an app installed in Jira.\n\nIf the JWT token corresponds to an app that does not define `jiraBuildInfoProvider` module it will be\nrejected with a 403.\n\nSee https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.\n", "required": true, "schema": { "type": "string", "pattern": "JWT \\S+" } } ] }, "/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. The result will be what is currently stored, ignoring any pending updates or deletes. Only apps that define the `jiraBuildInfoProvider` module can access this resource. This resource requires the 'READ' scope.", "parameters": [ { "name": "pipelineId", "in": "path", "description": "The `pipelineId` of the build.", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "buildNumber", "in": "path", "description": "The `buildNumber` of the build.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "The build data currently stored for the given key.", "content": { "application/json": { "schema": { "description": "Data related to a single build", "required": [ "pipelineId", "buildNumber", "displayName", "url", "state", "lastUpdated", "updateSequenceNumber", "issueKeys" ], "properties": { "schemaVersion": { "description": "The schema version used for this data. Placeholder to support potential schema changes in the future.", "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, plan key etc. - whatever logical unit you use to group a sequence of builds. The combination of `pipelineId` and `buildNumber` must uniquely identify a build you have provided.", "type": "string", "maxLength": 255, "example": "my-build-plan" }, "buildNumber": { "description": "Identifies a build within the sequence of builds identified by the build `pipelineId`. Used to identify the 'most recent' build in that sequence of builds. The combination of `pipelineId` and `buildNumber` must uniquely identify a build you have provided.", "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`, in the case of out-of-order receipt of update requests. It must be a monotonically increasing number. For example, epoch time could be one way to generate the `updateSequenceNumber`. Updates for a build that is received with an `updateSqeuenceNumber` less than or equal to what is currently stored will be ignored.", "type": "integer", "format": "int64", "example": 1523494301448 }, "displayName": { "description": "The human-readable name for the build. Will be shown in the UI.", "type": "string", "maxLength": 255, "example": "My Project build #16" }, "description": { "description": "An optional description to attach to this build. This may be anything that makes sense in your system.", "type": "string", "maxLength": 255, "example": "My Project build #16: Failed" }, "label": { "description": "A human-readable string that to provide information about the build.", "type": "string", "maxLength": 255 }, "url": { "description": "The URL to this build in your system.", "type": "string", "format": "URL" }, "state": { "description": "The state of this build", "type": "string", "enum": [ "pending", "in_progress", "successful", "failed", "cancelled", "unknown" ], "example": "failed" }, "lastUpdated": { "description": "The last-updated timestamp to present to the user as a summary of the state of the build.", "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. You are free to associate issue keys in any way you like. However, we recommend that you use the name of the branch the build was executed on, and extract issue keys from that name using a simple regex. This has the advantage that it provides an intuitive association of builds to issue keys.", "type": "array", "items": { "description": "An issue key that references an issue in Jira.\n", "type": "string", "pattern": "\\w{1,255}-\\d{1,255}", "example": "ISSUE-123" }, "minItems": 1, "maxItems": 100 }, "testInfo": { "description": "Optional information about tests that were executed during the build.", "type": "object", "required": [ "totalNumber", "numberPassed", "numberFailed" ], "properties": { "totalNumber": { "description": "The total number of tests considered during a build.", "type": "integer", "format": "int64", "example": 150 }, "numberPassed": { "description": "The number of tests that passed during a build.", "type": "integer", "format": "int64", "example": 145 }, "numberFailed": { "description": "The number of tests that failed during a build.", "type": "integer", "format": "int64", "example": 5 }, "numberSkipped": { "description": "The number of tests that were skipped during a build.", "type": "integer", "format": "int64", "default": 0, "example": 0 } } }, "references": { "description": "Optional information that links a build to a commit, branch etc.", "type": "array", "items": { "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": { "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" } } }, "ref": { "description": "Details about the ref (branch, tag etc.) 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" } } } } }, "minItems": 1, "maxItems": 5 } } } } } }, "401": { "description": "Missing a JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the `jiraBuildInfoProvider` module, or the app does not define the 'READ' scope." }, "404": { "description": "No build data found for the given key." }, "429": { "description": "API rate limit has been exceeded." }, "503": { "description": "Service is unavailable due to maintenance or other reasons." }, "default": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "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." } } } } } } } }, "x-atlassian-connect-scope": "READ" }, "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. Deletion is performed asynchronously. The `getBuildByKey` operation can be used to confirm that data has been deleted successfully (if needed). Only apps that define the `jiraBuildInfoProvider` module can access this resource. This resource requires the 'DELETE' scope.", "parameters": [ { "name": "pipelineId", "in": "path", "description": "The `pipelineId` of the build to delete.", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "name": "buildNumber", "in": "path", "description": "The `buildNumber` of the build to delete.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "_updateSequenceNumber", "in": "query", "description": "An optional `updateSequenceNumber` to use to control deletion. Only stored data with an `updateSequenceNumber` less than or equal to that provided will be deleted. This can be used help ensure submit/delete requests are applied correctly if issued close together.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "202": { "description": "Delete has been accepted. Data will eventually be removed from Jira if it exists." }, "401": { "description": "Missing a JWT token, or token is invalid." }, "403": { "description": "The JWT token used does not correspond to an app that defines the `jiraBuildInfoProvider` module, or the app does not define the 'DELETE' scope." }, "429": { "description": "API rate limit has been exceeded." }, "503": { "description": "Service is unavailable due to maintenance or other reasons." }, "default": { "description": "An unknown error has occurred.", "content": { "application/json": { "schema": { "description": "Messages supplied in the case of an error.", "type": "array", "minItems": 1, "items": { "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." } } } } } } } }, "x-atlassian-connect-scope": "DELETE" }, "parameters": [ { "name": "Authorization", "in": "header", "description": "All requests must be signed with a Connect JWT token that corresponds to an app installed in Jira.\n\nIf the JWT token corresponds to an app that does not define `jiraBuildInfoProvider` module it will be\nrejected with a 403.\n\nSee https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more details.\n", "required": true, "schema": { "type": "string", "pattern": "JWT \\S+" } } ] } }, "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\nLooking for the REST API reference for a different Jira version? Follow the links below.\n\n * [Jira Software Server (latest version) REST API](https://docs.atlassian.com/jira-software/REST/server/)\n * [List of all Jira Software REST APIs](https://docs.atlassian.com/jira-software/REST/)\n\nJira Agile is an add-on, which is part of the Jira Software application and provides the Agile planning features like\nboards and sprints. Jira Software is built on the Jira platform. As such, there is a natural 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://docs.atlassian.com/jira/REST/cloud/).\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 [Development Information](#api-group-FeatureFlags) \nand [Feature Flags](#api-group-FeatureFlags) 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.\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## 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-atlassian-force-account-id** (request): Operations with the `x-atlassian-force-account-id: true` header will behave as if GDPR \nchanges are enforced (for example, deprecated fields removed). Use this header to test if your integration is GDPR-compliant. See the \n[migration guide](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/#testing-your-gdpr-changes) \nfor details.\n- **X-AUSERNAME** (response): This response header contains either the username of the authenticated user or `anonymous`. \nNote that this header is not returned if the request includes the `x-atlassian-force-account-id: true` header.\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" } ] }, "servers": [ { "url": "//your-domain.atlassian.net/rest/" } ], "components": { "requestBodies": { "com.atlassian.greenhopper.api.rest.BacklogResource.moveIssuesToBacklogForBoard_postIssuerankrequestbean": { "content": { "application/json": { "schema": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "string" } }, "rankBeforeIssue": { "type": "string" }, "rankAfterIssue": { "type": "string" }, "rankCustomFieldId": { "type": "integer", "format": "int64" } } }, "examples": { "x-example": { "summary": "Example", "description": "This example was copied over from Swagger V2 into this OAS 3.0 file.", "value": { "issues": [ "PR-1", "10001", "PR-3" ], "rankBeforeIssue": "PR-4", "rankCustomFieldId": 10521 } } } } }, "required": true }, "com.atlassian.greenhopper.api.rest.BacklogResource.moveIssuesToBacklog_postIssueassignrequestbean": { "content": { "application/json": { "schema": { "type": "object", "properties": { "issues": { "type": "array", "uniqueItems": true, "items": { "type": "string" } } } }, "examples": { "x-example": { "summary": "Example", "description": "This example was copied over from Swagger V2 into this OAS 3.0 file.", "value": { "issues": [ "PR-1", "10001", "PR-3" ] } } } } }, "required": true }, "com.atlassian.greenhopper.api.rest.SprintResource.partiallyUpdateSprint_postSprintbean": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "self": { "type": "string", "format": "uri" }, "state": { "type": "string" }, "name": { "type": "string" }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "completeDate": { "type": "string" }, "originBoardId": { "type": "integer", "format": "int64" }, "goal": { "type": "string" } } }, "examples": { "x-example": { "summary": "Example", "description": "This example was copied over from Swagger V2 into this OAS 3.0 file.", "value": { "name": "new name" } } } } }, "required": true } }, "securitySchemes": { "atlassianCloudBasicAuth": { "scheme": "basic", "type": "http", "description": "You require basic auth to access this API." } } }, "security": [ { "atlassianCloudBasicAuth": [] } ] }