openapi: 3.2.0 info: contact: url: https://getsupport.atlassian.com description: Jira Software Cloud REST API documentation license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html termsOfService: http://atlassian.com/terms/ title: Jira Software Cloud Security Information API version: 1001.0.0 servers: - url: https://your-domain.atlassian.net tags: - name: Security Information description: Send security information to Jira Software and enable your teams to turn unplanned vulnerabilities into planned and tracked work. paths: /rest/security/1.0/linkedWorkspaces/bulk: parameters: - name: Authorization in: header description: 'All requests must be authenticated as an app — either with a Connect JWT token for Connect apps, or with an OAuth 2.0 access token for Forge and OAuth 2.0 apps — that corresponds to the Provider app installed in Jira. If the app does not define a security information provider module, or does not have the required scope, the request will be rejected with a 403. Read [understanding jwt](https://developer.atlassian.com/blog/2015/01/understanding-jwt/) for more details about Connect JWT tokens. ' required: true schema: type: string pattern: JWT \S+ post: operationId: submitWorkspaces summary: Submit Security Workspaces to link tags: - Security Information description: Insert Security Workspace IDs to establish a relationship between them and the Jira site the app is installed on. If a relationship between the workspace ID and Jira already exists then the workspace ID will be ignored and Jira will process the rest of the entries. requestBody: content: application/json: schema: title: SubmitSecurityWorkspacesRequest description: The payload used to submit (update / insert) Security Workspace IDs. required: - workspaceIds properties: workspaceIds: title: Security Workspace IDs description: 'The IDs of Security Workspaces to link to this Jira site. These must follow this regex pattern: `[a-zA-Z0-9\\-_.~@:{}=]+(\/[a-zA-Z0-9\\-_.~@:{}=]+)*` ' type: array items: type: string pattern: '[a-zA-Z0-9\-_.~@:{}=]+(/[a-zA-Z0-9\-_.~@:{}=]+)*' example: - 111-222-333 - 444-555-666 minItems: 1 maxItems: 100 description: 'Security Workspace IDs to submit. ' required: true responses: '202': description: 'Submission accepted. Each submitted Security Workspace ID will be linked to Jira. ' '400': description: 'Request has incorrect format. ' content: application/json: schema: title: ErrorMessages description: Messages supplied in the case of an error. type: array minItems: 1 items: title: ErrorMessage 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 app does not define a security info provider module, or does not have the required scope to access this resource. ' '413': description: 'Set of Ids is too large. Submit fewer Ids in each payload. ' content: application/json: schema: title: ErrorMessages description: Messages supplied in the case of an error. type: array minItems: 1 maxItems: 100 items: title: ErrorMessage 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: title: ErrorMessages description: Messages supplied in the case of an error. type: array minItems: 1 items: title: ErrorMessage 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: WRITE security: - OAuth2: - write:security:jira x-atlassian-data-security-policy: - app-access-rule-exempt: false delete: operationId: deleteLinkedWorkspaces summary: Delete linked Security Workspaces tags: - Security Information description: 'Bulk delete all linked Security Workspaces that match the given request. e.g. DELETE /bulk?workspaceIds=111-222-333,444-555-666' responses: '202': description: 'Delete accepted. Workspaces and related data will eventually be removed from Jira. ' '400': description: 'Request has incorrect format. ' content: application/json: schema: title: ErrorMessages description: Messages supplied in the case of an error. type: array minItems: 1 maxItems: 100 items: title: ErrorMessage 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 app does not define a security info provider module, or does not have the required scope to access this resource. ' '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: title: ErrorMessages description: Messages supplied in the case of an error. type: array minItems: 1 maxItems: 1 items: title: ErrorMessage 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 security: - OAuth2: - delete:security:jira x-atlassian-data-security-policy: - app-access-rule-exempt: false /rest/security/1.0/linkedWorkspaces: parameters: - name: Authorization in: header description: 'All requests must be authenticated as an app — either with a Connect JWT token for Connect apps, or with an OAuth 2.0 access token for Forge and OAuth 2.0 apps — that corresponds to the Provider app installed in Jira. If the app does not define a security information provider module, or does not have the required scope, the request will be rejected with a 403. Read [understanding jwt](https://developer.atlassian.com/blog/2015/01/understanding-jwt/) for more details about Connect JWT tokens. ' required: true schema: type: string pattern: JWT \S+ get: operationId: getLinkedWorkspaces summary: Get linked Security Workspaces tags: - Security Information description: 'Retrieve all Security Workspaces linked with the Jira site. The result will be what is currently stored, ignoring any pending updates or deletes.' responses: '200': description: 'A list of all stored workspace IDs. ' content: application/json: schema: title: SecurityWorkspaceIds description: The payload of linked Security Workspace IDs. required: - workspaceIds properties: workspaceIds: title: Security Workspace IDs description: 'The IDs of Security Workspaces that are linked to this Jira site. ' type: array items: type: string example: - 111-222-333 - 444-555-666 minItems: 1 '401': description: 'Missing a JWT token, or token is invalid. ' '403': description: 'The app does not define a security info provider module, or does not have the required scope to access this resource. ' '404': description: 'No data found for the given workspace 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: title: ErrorMessages description: Messages supplied in the case of an error. type: array minItems: 1 items: title: ErrorMessage 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 security: - OAuth2: - read:security:jira x-atlassian-data-security-policy: - app-access-rule-exempt: false /rest/security/1.0/linkedWorkspaces/{workspaceId}: parameters: - name: Authorization in: header description: 'All requests must be authenticated as an app — either with a Connect JWT token for Connect apps, or with an OAuth 2.0 access token for Forge and OAuth 2.0 apps — that corresponds to the Provider app installed in Jira. If the app does not define a security information provider module, or does not have the required scope, the request will be rejected with a 403. Read [understanding jwt](https://developer.atlassian.com/blog/2015/01/understanding-jwt/) for more details about Connect JWT tokens. ' required: true schema: type: string pattern: JWT \S+ get: operationId: getLinkedWorkspaceById summary: Get a linked Security Workspace by ID tags: - Security Information description: 'Retrieve a specific Security Workspace linked to the Jira site for the given workspace ID. The result will be what is currently stored, ignoring any pending updates or deletes.' parameters: - name: workspaceId in: path description: 'The ID of the workspace to fetch. ' required: true schema: type: string maxLength: 255 responses: '200': description: 'The Security Workspace information stored for the given ID. ' content: application/json: schema: title: SecurityWorkspaceResponse description: The Security Workspace information stored for the given ID. required: - workspaceId - updatedAt properties: workspaceId: description: 'The Security Workspace ID ' type: string example: 111-222-333 updatedAt: description: 'Latest date and time that the Security Workspace was updated in Jira. ' type: string format: date-time example: '2020-01-17T09:30:00.000Z' '401': description: 'Missing a JWT token, or token is invalid. ' '403': description: 'The app does not define a security info provider module, or does not have the required scope to access this resource. ' '404': description: 'No data found for the given workspace 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: title: ErrorMessages description: Messages supplied in the case of an error. type: array minItems: 1 items: title: ErrorMessage 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 security: - OAuth2: - read:security:jira x-atlassian-data-security-policy: - app-access-rule-exempt: false /rest/security/1.0/bulk: parameters: - name: Authorization in: header description: 'All requests must be authenticated as an app — either with a Connect JWT token for Connect apps, or with an OAuth 2.0 access token for Forge and OAuth 2.0 apps — that corresponds to the Provider app installed in Jira. If the app does not define a security information provider module, or does not have the required scope, the request will be rejected with a 403. Read [understanding jwt](https://developer.atlassian.com/blog/2015/01/understanding-jwt/) for more details about Connect JWT tokens. ' required: true schema: type: string pattern: JWT \S+ post: operationId: submitVulnerabilities summary: Submit Vulnerability data tags: - Security Information description: 'Update / Insert Vulnerability data. Vulnerabilities are identified by their ID, any existing Vulnerability data with the same ID will be replaced if it exists and the updateSequenceNumber of the existing data is less than the incoming data. Submissions are performed asynchronously. Most updates are available within a short period of time but may take some time during peak load and/or maintenance times. The GET vulnerability endpoint can be used to confirm that data has been stored successfully (if needed). In the case of multiple Vulnerabilities being submitted in one request, each is validated individually prior to submission. Details of Vulnerabilities that failed submission (if any) are available in the response object. A maximum of 1000 vulnerabilities can be submitted in one request.' requestBody: content: application/json: schema: title: SubmitVulnerabilitiesRequest description: The payload used to submit (update / insert) Vulnerability data. required: - vulnerabilities properties: operationType: type: string description: 'Indicates the operation being performed by the provider system when sending this data. "NORMAL" - Data received during real-time, user-triggered actions (e.g. user closed or updated a vulnerability). "SCAN" - Data sent through some automated process (e.g. some periodically scheduled repository scan). "BACKFILL" - Data received while backfilling existing data (e.g. pushing historical vulnerabilities when re-connect a workspace). Default is "NORMAL". "NORMAL" traffic has higher priority but tighter rate limits, "SCAN" traffic has medium priority and looser limits, "BACKFILL" has lower priority and much looser limits ' example: SCAN enum: - NORMAL - SCAN - BACKFILL properties: title: Properties description: 'Properties assigned to vulnerability data that can then be used for delete / query operations. Examples might be an account or user ID that can then be used to clean up data if an account is removed from the Provider system. Properties are supplied as key/value pairs, and a maximum of 5 properties can be supplied, keys cannot contain '':'' or start with ''_''. ' type: object additionalProperties: type: string maxLength: 255 maxProperties: 5 example: accountId: account-234 projectId: project-123 vulnerabilities: type: array items: title: Vulnerability details required: - schemaVersion - id - updateSequenceNumber - displayName - containerId - description - url - type - introducedDate - lastUpdated - severity - status properties: schemaVersion: description: 'The VulnerabilityData schema version used for this vulnerability 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 Vulnerability. Must be unique for a given Provider. ' type: string maxLength: 255 example: 111-222-333 updateSequenceNumber: description: 'An ID used to apply an ordering to updates for this Vulnerability 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 Vulnerability and increment that on each update to Jira). Updates for a Vulnerability that are received with an updateSequenceId lower than what is currently stored will be ignored. ' type: integer format: int64 example: 1523494301448 containerId: description: 'The identifier of the Container where this Vulnerability was found. Must be unique for a given Provider. This must follow this regex pattern: `[a-zA-Z0-9\\-_.~@:{}=]+(/[a-zA-Z0-9\\-_.~@:{}=]+)*` ' type: string maxLength: 255 example: 111-222-333 pattern: '[a-zA-Z0-9\-_.~@:{}=]+(/[a-zA-Z0-9\-_.~@:{}=]+)*' displayName: description: 'The human-readable name for the Vulnerability. Will be shown in the UI. If not provided, will use the ID for display. ' type: string maxLength: 255 example: curl/libcurl3 - Buffer Override description: description: 'A description of the issue in markdown format that will be shown in the UI and used when creating Jira Issues. HTML tags are not supported in the markdown format. For creating a new line `\n` can be used. Read more about the accepted markdown transformations [here](https://atlaskit.atlassian.com/packages/editor/editor-markdown-transformer). ' type: string maxLength: 5000 example: '## Overview Affected versions of this package are vulnerable to MeltLeak' url: description: 'A URL users can use to link to a summary view of this vulnerability, if appropriate. This could be any location that makes sense in the Provider system (e.g. if the summary information comes from a specific project, it might make sense to link the user to the vulnerability in that project). ' type: string format: uri maxLength: 2000 example: https://example.com/project/CWE-123/summary type: description: The type of Vulnerability detected. type: string enum: - sca - sast - dast - unknown example: sca introducedDate: description: 'The timestamp to present to the user that shows when the Vulnerability was introduced. Expected format is an RFC3339 formatted string. ' type: string format: date-time example: '2018-01-20T23:27:25.000Z' lastUpdated: description: 'The last-updated timestamp to present to the user the last time the Vulnerability was updated. Expected format is an RFC3339 formatted string. ' type: string format: date-time example: '2018-01-20T23:27:25.000Z' severity: title: VulnerabilitySeverity description: 'Severity information for a single Vulnerability. This is the severity information that will be presented to the user on e.g. the Jira Security screen. ' required: - level properties: level: description: The severity level of the Vulnerability. type: string enum: - critical - high - medium - low - unknown example: critical minItems: 1 identifiers: description: 'The identifying information for the Vulnerability. ' type: array items: title: Identifier description: 'The identifiers object that contains public/private information identifying the Vulnerability. ' required: - displayName - url properties: displayName: description: 'The display name of the Vulnerability identified. ' type: string maxLength: 255 example: CWE-123 url: description: 'A URL users can use to link to the definition of the Vulnerability identified. ' type: string format: uri maxLength: 2000 example: https://cwe.mitre.org/data/definitions/123.html minItems: 1 maxItems: 100 status: description: 'The current status of the Vulnerability. ' title: VulnerabilityStatus type: string enum: - open - closed - ignored - unknown example: open additionalInfo: title: VulnerabilityAdditionalInfo description: 'Extra information (optional). This data will be shown in the security feature under the vulnerability displayName. ' type: object required: - content properties: content: description: 'The content of the additionalInfo. ' type: string maxLength: 255 example: More information on the vulnerability, as a string url: description: 'Optional URL linking to the information ' type: string format: uri maxLength: 2000 example: https://example.com/project/CWE-123/additionalInfo addAssociations: description: 'The associations (e.g. Jira issue) to add in addition to the currently stored associations of the Security Vulnerability. ' type: array items: anyOf: - title: IssueIdOrKeysAssociation description: 'An association type referencing Jira issue id or keys. ' type: object required: - associationType - values properties: associationType: description: 'Defines the association type. ' type: string enum: - issueIdOrKeys example: issueIdOrKeys values: description: 'The Jira issue id or keys to associate the Security information with. The number of values counted across all associationTypes (issueIdOrKeys) must not exceed a limit of 500. ' type: array items: title: IssueIdOrKeys description: 'A Jira issue id or key. ' type: string maxLength: 255 example: some-issue-key minItems: 1 maxItems: 500 example: associationType: issueIdOrKeys values: - PROJ-1234 minItems: 0 maxItems: 1 removeAssociations: description: 'The associations (e.g. Jira issue) to remove from currently stored associations of the Security Vulnerability. ' type: array items: anyOf: - title: IssueIdOrKeysAssociation description: 'An association type referencing Jira issue id or keys. ' type: object required: - associationType - values properties: associationType: description: 'Defines the association type. ' type: string enum: - issueIdOrKeys example: issueIdOrKeys values: description: 'The Jira issue id or keys to associate the Security information with. The number of values counted across all associationTypes (issueIdOrKeys) must not exceed a limit of 500. ' type: array items: title: IssueIdOrKeys description: 'A Jira issue id or key. ' type: string maxLength: 255 example: some-issue-key minItems: 1 maxItems: 500 example: associationType: issueIdOrKeys values: - PROJ-1234 minItems: 0 maxItems: 1 associationsLastUpdated: description: 'An ISO-8601 Date-time string representing the last time the provider updated associations on this entity. Expected format is an RFC3339 formatted string. ' type: string format: date-time example: '2018-01-20T23:27:25.000Z' associationsUpdateSequenceNumber: description: 'A sequence number to compare when writing entity associations to the database. This can be any monotonically increasing number. A highly recommended implementation is to use epoch millis. This is an optional field. If it is not provided it will default to being equal to the corresponding entity''s `updateSequenceNumber`. Associations are written following a LastWriteWins strategy, association that are received with an associationsUpdateSequenceNumber lower than what is currently stored will be ignored. ' type: integer format: int64 example: 1523494301448 additionalProperties: false description: 'Data related to a specific vulnerability in a specific workspace that the vulnerability is present in. Must specify at least one association. ' minItems: 1 maxItems: 1000 providerMetadata: title: ProviderMetadata description: 'Information about the provider. This is useful for auditing, logging, debugging, and other internal uses. Information in this property is not considered private, so it should not contain personally identifiable information ' type: object properties: product: type: string description: An optional name of the source of the vulnerabilities. example: Atlassian Security Platform 2.1.0 description: 'Vulnerability data to submit. ' required: true responses: '202': description: 'Submission accepted. Each Vulnerability submitted in a valid format will eventually be available in Jira. Details of any Vulnerabilities that were submitted but failed submission (due to data format problems, etc.) are available in the response object. ' content: application/json: schema: title: SubmitVulnerabilitiesResponse description: 'The result of a successful submitVulnerabilities request. ' properties: acceptedVulnerabilities: description: 'The IDs of Vulnerabilities that have been accepted for submission. A Vulnerability may be rejected if it was only associated with unknown project keys. Note that a Vulnerability that isn''t updated due to it''s updateSequenceNumber being out of order is not considered a failed submission. ' type: array items: type: string example: - 111-222-333 - 444-555-666 failedVulnerabilities: description: 'Details of Vulnerabilities that have not been accepted for submission, usually due to a problem with the request data. The object (if present) will be keyed by Vulnerability ID and include any errors associated with that Vulnerability that have prevented it being submitted. ' type: object additionalProperties: type: array items: title: ErrorMessage 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. unknownAssociations: description: 'Associations (e.g. Service IDs) that are not known on this Jira instance (if any). If a Vulnerability has been associated with any other association other than those in this array it will still be stored against those valid associations. If a Vulnerability was only associated with the associations in this array, it is deemed to be invalid and it won''t be persisted. ' type: array items: anyOf: - title: IssueIdOrKeysAssociation description: 'An association type referencing Jira issue id or keys. ' type: object required: - associationType - values properties: associationType: description: 'Defines the association type. ' type: string enum: - issueIdOrKeys example: issueIdOrKeys values: description: 'The Jira issue id or keys to associate the Security information with. The number of values counted across all associationTypes (issueIdOrKeys) must not exceed a limit of 500. ' type: array items: title: IssueIdOrKeys description: 'A Jira issue id or key. ' type: string maxLength: 255 example: some-issue-key minItems: 1 maxItems: 500 example: associationType: issueIdOrKeys values: - PROJ-1234 '400': description: 'Request has incorrect format. Note that in the case of an individual Vulnerability 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 Vulnerability will be contained in the response object. ' content: application/json: schema: title: ErrorMessages description: Messages supplied in the case of an error. type: array minItems: 1 items: title: ErrorMessage 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 app does not define a security info provider module, or does not have the required scope to access this resource. ' '413': description: 'Data is too large. Submit fewer Vulnerabilities in each payload. ' content: application/json: schema: title: ErrorMessages description: Messages supplied in the case of an error. type: array minItems: 1 items: title: ErrorMessage 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. ' headers: X-RateLimit-Remaining: schema: type: integer description: The number of remaining possible requests in current rate limit window. X-RateLimit-Reset: schema: type: string description: The date in ISO 8601 format when the rate limit values will be next reset. X-RateLimit-Limit: schema: type: integer description: The maximum possible requests in a window of one minute. Retry-After: schema: type: integer description: The number of seconds to wait before making a follow-up request. '503': description: 'Service is unavailable due to maintenance or other reasons. ' default: description: 'An unknown error has occurred. ' content: application/json: schema: title: ErrorMessages description: Messages supplied in the case of an error. type: array minItems: 1 items: title: ErrorMessage 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: WRITE security: - OAuth2: - write:security:jira x-atlassian-data-security-policy: - app-access-rule-exempt: false /rest/security/1.0/bulkByProperties: parameters: - name: Authorization in: header description: 'All requests must be authenticated as an app — either with a Connect JWT token for Connect apps, or with an OAuth 2.0 access token for Forge and OAuth 2.0 apps — that corresponds to the Provider app installed in Jira. If the app does not define a security information provider module, or does not have the required scope, the request will be rejected with a 403. Read [understanding jwt](https://developer.atlassian.com/blog/2015/01/understanding-jwt/) for more details about Connect JWT tokens. ' required: true schema: type: string pattern: JWT \S+ delete: operationId: deleteVulnerabilitiesByProperty summary: Delete Vulnerabilities by Property tags: - Security Information description: 'Bulk delete all Vulnerabilities that match the given request. 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). Read the POST bulk endpoint documentation for more details. e.g. DELETE /bulkByProperties?accountId=account-123&createdBy=user-456 Deletion is performed asynchronously. The GET vulnerability endpoint can be used to confirm that data has been deleted successfully (if needed).' 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: title: ErrorMessages description: Messages supplied in the case of an error. type: array minItems: 1 items: title: ErrorMessage 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 app does not define a security info provider module, or does not have the required scope to access this resource. ' '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: title: ErrorMessages description: Messages supplied in the case of an error. type: array minItems: 1 items: title: ErrorMessage 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 security: - OAuth2: - delete:security:jira x-atlassian-data-security-policy: - app-access-rule-exempt: false /rest/security/1.0/vulnerability/{vulnerabilityId}: parameters: - name: Authorization in: header description: 'All requests must be authenticated as an app — either with a Connect JWT token for Connect apps, or with an OAuth 2.0 access token for Forge and OAuth 2.0 apps — that corresponds to the Provider app installed in Jira. If the app does not define a security information provider module, or does not have the required scope, the request will be rejected with a 403. Read [Understanding JWT](https://developer.atlassian.com/blog/2015/01/understanding-jwt/) for more details about Connect JWT tokens. ' required: true schema: type: string get: operationId: getVulnerabilityById summary: Get a Vulnerability by ID tags: - Security Information description: 'Retrieve the currently stored Vulnerability data for the given ID. The result will be what is currently stored, ignoring any pending updates or deletes.' parameters: - name: vulnerabilityId in: path description: 'The ID of the Vulnerability to fetch. ' required: true schema: type: string maxLength: 255 responses: '200': description: 'The Vulnerability data currently stored for the given ID. ' content: application/json: schema: title: Vulnerability details required: - schemaVersion - id - updateSequenceNumber - displayName - containerId - description - url - type - introducedDate - lastUpdated - severity - status properties: schemaVersion: description: 'The VulnerabilityData schema version used for this vulnerability 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 Vulnerability. Must be unique for a given Provider. ' type: string maxLength: 255 example: 111-222-333 updateSequenceNumber: description: 'An ID used to apply an ordering to updates for this Vulnerability 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 Vulnerability and increment that on each update to Jira). Updates for a Vulnerability that are received with an updateSequenceId lower than what is currently stored will be ignored. ' type: integer format: int64 example: 1523494301448 containerId: description: 'The identifier of the Container where this Vulnerability was found. Must be unique for a given Provider. This must follow this regex pattern: `[a-zA-Z0-9\\-_.~@:{}=]+(/[a-zA-Z0-9\\-_.~@:{}=]+)*` ' type: string maxLength: 255 example: 111-222-333 pattern: '[a-zA-Z0-9\-_.~@:{}=]+(/[a-zA-Z0-9\-_.~@:{}=]+)*' displayName: description: 'The human-readable name for the Vulnerability. Will be shown in the UI. If not provided, will use the ID for display. ' type: string maxLength: 255 example: curl/libcurl3 - Buffer Override description: description: 'A description of the issue in markdown format that will be shown in the UI and used when creating Jira Issues. HTML tags are not supported in the markdown format. For creating a new line `\n` can be used. Read more about the accepted markdown transformations [here](https://atlaskit.atlassian.com/packages/editor/editor-markdown-transformer). ' type: string maxLength: 5000 example: '## Overview Affected versions of this package are vulnerable to MeltLeak' url: description: 'A URL users can use to link to a summary view of this vulnerability, if appropriate. This could be any location that makes sense in the Provider system (e.g. if the summary information comes from a specific project, it might make sense to link the user to the vulnerability in that project). ' type: string format: uri maxLength: 2000 example: https://example.com/project/CWE-123/summary type: description: The type of Vulnerability detected. type: string enum: - sca - sast - dast - unknown example: sca introducedDate: description: 'The timestamp to present to the user that shows when the Vulnerability was introduced. Expected format is an RFC3339 formatted string. ' type: string format: date-time example: '2018-01-20T23:27:25.000Z' lastUpdated: description: 'The last-updated timestamp to present to the user the last time the Vulnerability was updated. Expected format is an RFC3339 formatted string. ' type: string format: date-time example: '2018-01-20T23:27:25.000Z' severity: title: VulnerabilitySeverity description: 'Severity information for a single Vulnerability. This is the severity information that will be presented to the user on e.g. the Jira Security screen. ' required: - level properties: level: description: The severity level of the Vulnerability. type: string enum: - critical - high - medium - low - unknown example: critical minItems: 1 identifiers: description: 'The identifying information for the Vulnerability. ' type: array items: title: Identifier description: 'The identifiers object that contains public/private information identifying the Vulnerability. ' required: - displayName - url properties: displayName: description: 'The display name of the Vulnerability identified. ' type: string maxLength: 255 example: CWE-123 url: description: 'A URL users can use to link to the definition of the Vulnerability identified. ' type: string format: uri maxLength: 2000 example: https://cwe.mitre.org/data/definitions/123.html minItems: 1 maxItems: 100 status: description: 'The current status of the Vulnerability. ' title: VulnerabilityStatus type: string enum: - open - closed - ignored - unknown example: open additionalInfo: title: VulnerabilityAdditionalInfo description: 'Extra information (optional). This data will be shown in the security feature under the vulnerability displayName. ' type: object required: - content properties: content: description: 'The content of the additionalInfo. ' type: string maxLength: 255 example: More information on the vulnerability, as a string url: description: 'Optional URL linking to the information ' type: string format: uri maxLength: 2000 example: https://example.com/project/CWE-123/additionalInfo addAssociations: description: 'The associations (e.g. Jira issue) to add in addition to the currently stored associations of the Security Vulnerability. ' type: array items: anyOf: - title: IssueIdOrKeysAssociation description: 'An association type referencing Jira issue id or keys. ' type: object required: - associationType - values properties: associationType: description: 'Defines the association type. ' type: string enum: - issueIdOrKeys example: issueIdOrKeys values: description: 'The Jira issue id or keys to associate the Security information with. The number of values counted across all associationTypes (issueIdOrKeys) must not exceed a limit of 500. ' type: array items: title: IssueIdOrKeys description: 'A Jira issue id or key. ' type: string maxLength: 255 example: some-issue-key minItems: 1 maxItems: 500 example: associationType: issueIdOrKeys values: - PROJ-1234 minItems: 0 maxItems: 1 removeAssociations: description: 'The associations (e.g. Jira issue) to remove from currently stored associations of the Security Vulnerability. ' type: array items: anyOf: - title: IssueIdOrKeysAssociation description: 'An association type referencing Jira issue id or keys. ' type: object required: - associationType - values properties: associationType: description: 'Defines the association type. ' type: string enum: - issueIdOrKeys example: issueIdOrKeys values: description: 'The Jira issue id or keys to associate the Security information with. The number of values counted across all associationTypes (issueIdOrKeys) must not exceed a limit of 500. ' type: array items: title: IssueIdOrKeys description: 'A Jira issue id or key. ' type: string maxLength: 255 example: some-issue-key minItems: 1 maxItems: 500 example: associationType: issueIdOrKeys values: - PROJ-1234 minItems: 0 maxItems: 1 associationsLastUpdated: description: 'An ISO-8601 Date-time string representing the last time the provider updated associations on this entity. Expected format is an RFC3339 formatted string. ' type: string format: date-time example: '2018-01-20T23:27:25.000Z' associationsUpdateSequenceNumber: description: 'A sequence number to compare when writing entity associations to the database. This can be any monotonically increasing number. A highly recommended implementation is to use epoch millis. This is an optional field. If it is not provided it will default to being equal to the corresponding entity''s `updateSequenceNumber`. Associations are written following a LastWriteWins strategy, association that are received with an associationsUpdateSequenceNumber lower than what is currently stored will be ignored. ' type: integer format: int64 example: 1523494301448 additionalProperties: false description: 'Data related to a specific vulnerability in a specific workspace that the vulnerability is present in. Must specify at least one association. ' '401': description: 'Missing a JWT token, or token is invalid. ' '403': description: 'The app does not define a security info provider module, or does not have the required scope to access this resource. ' '404': description: 'No data found for the given Vulnerability 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: title: ErrorMessages description: Messages supplied in the case of an error. type: array minItems: 1 items: title: ErrorMessage 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 security: - OAuth2: - read:security:jira x-atlassian-data-security-policy: - app-access-rule-exempt: false delete: operationId: deleteVulnerabilityById summary: Delete a Vulnerability by ID tags: - Security Information description: 'Delete the Vulnerability data currently stored for the given ID. Deletion is performed asynchronously. The GET vulnerability endpoint can be used to confirm that data has been deleted successfully (if needed).' parameters: - name: vulnerabilityId in: path description: 'The ID of the Vulnerability to delete. ' required: true schema: type: string maxLength: 255 responses: '202': description: 'Delete has been accepted. If the data exists, it will eventually be removed from Jira. ' '401': description: 'Missing a JWT token, or token is invalid. ' '403': description: 'The app does not define a security info provider module, or does not have the required scope to access this resource. ' '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: title: ErrorMessages description: Messages supplied in the case of an error. type: array minItems: 1 items: title: ErrorMessage 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 security: - OAuth2: - delete:security:jira x-atlassian-data-security-policy: - app-access-rule-exempt: false components: securitySchemes: OAuth2: description: OAuth2 scopes for Jira flows: authorizationCode: authorizationUrl: https://auth.atlassian.com/authorize scopes: delete:board-scope.admin:jira-software: Remove board configuration, features, and properties. delete:sprint:jira-software: Delete sprints and their properties. manage:jira-configuration: Configure Jira settings that require the Jira administrators permission, for example, create projects and custom fields, view workflows, manage issue link types. manage:jira-project: Create and edit project settings and create new project-level objects, for example, versions, components. manage:jira-webhook: Manage Jira webhooks. Enables an OAuth app to register and unregister dynamic webhooks in Jira. It also provides for fetching of registered webhooks. read:board-scope.admin:jira-software: View configuration, features, filters, project, properties and quick filters related to the given board. read:board-scope:jira-software: View board and issues from a board, view issues from a backlog and view reports and versions. read:build:jira-software: View builds. read:deployment:jira-software: View deployments. read:epic:jira-software: View and search for epics, view issues related to an epic and issues without an epic. read:feature-flag:jira-software: View feature flags. read:issue:jira-software: View issues, issue estimations and field used for estimations. read:jira-user: View user information in Jira that you have access to, including usernames, email addresses, and avatars. read:jira-work: Read project and issue data. Search for issues and objects associated with issues (such as attachments and worklogs). read:remote-link:jira-software: View remote links. read:source-code:jira-software: View repositories and check if data exists for the supplied properties. read:sprint:jira-software: View sprints and sprint related issues and properties. write:board-scope.admin:jira-software: Create board, toggle features and set and delete properties. write:board-scope:jira-software: Move issues to a backlog and move issues from a backlog to a board. write:build:jira-software: Submit and delete build. write:deployment:jira-software: Submit and delete deployment. write:epic:jira-software: Remove issues from epic, move issues to epic, rank epics and partially update epics. A partial update means that fields not present in the request JSON will not be updated. write:feature-flag:jira-software: Submit and delete feature flag. write:issue:jira-software: Move (rank) issues and update estimation of the issue. write:jira-work: Create and edit issues in Jira, post comments, create worklogs, and delete issues. write:remote-link:jira-software: Submit and delete remote link. write:source-code:jira-software: Store and delete development information, delete repository and delete development information entity. write:sprint:jira-software: Save, move issues to sprints, and change the order of sprints. read:dev-info:jira: Read development information write:dev-info:jira: Write development information delete:dev-info:jira: Delete development information read:feature-flag-info:jira: Read feature flag information write:feature-flag-info:jira: Write feature flag information delete:feature-flag-info:jira: Delete feature flag information read:deployment-info:jira: Read deployment information write:deployment-info:jira: Write deployment information delete:deployment-info:jira: Delete deployment information read:build-info:jira: Read build information write:build-info:jira: Write build information delete:build-info:jira: Delete build information read:remote-link-info:jira: Read remote link information write:remote-link-info:jira: Write remote link information delete:remote-link-info:jira: Delete remote link information read:security:jira: Read security information write:security:jira: Write security information delete:security:jira: Delete security information tokenUrl: https://auth.atlassian.com/oauth/token type: oauth2 basicAuth: description: Basic authentication using email and API token scheme: basic type: http externalDocs: description: Find out more about Atlassian products and services. url: http://www.atlassian.com x-atlassian-narrative: documents: - anchor: introduction body: "Welcome to the Jira Software Cloud REST API reference. You can use this REST API to build add-ons for Jira Software,\ndevelop integrations between Jira Software and other applications, or script interactions with Jira Software. This page\ndocuments the REST resources available in Jira Software Cloud, along with expected HTTP response codes and sample\nrequests.\n\nJira Software is built on the Jira platform. As such, there is an overlap in functionality\nbetween what is provided by Jira Software and what is provided by the Jira platform. The REST API reference for the\nJira Cloud platform is here: [Jira Cloud platform REST API](https://developer.atlassian.com/cloud/jira/platform/rest).\n\n## Authentication\n\n### Authentication for Atlassian Connect add-ons\n\nIf you are integrating with the Jira REST APIs via an Atlassian Connect add-on, API calls are authenticated via JWT\n(JSON Web Tokens). This is built into the supported Atlassian Connect libraries. At a high level, authentication works\nby the add-on exchanging a security context with the application. This context is used to create and validate JWT\ntokens, embedded in API calls. To learn more, read the [Atlassian Connect authentication documentation](https://developer.atlassian.com/cloud/jira/platform/authentication-for-apps/).\n\nSome integration APIs such as [Feature Flags](#api-group-Feature-Flags) are only available to Atlassian Connect apps that\ndefine the relevant [module](https://developer.atlassian.com/cloud/jira/platform/about-jira-modules/) related to that API.\nOther APIs, such as the [Development Information](#api-group-Development-Information), [Builds](#api-group-Builds), and [Deployments](#api-group-Deployments) APIs\nare available to both Atlassian Connect apps and on-premises tools using Jira Software's\n[OAuth credentials](https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/) for system-to-system integration.\n\n### Authentication for REST API requests\n\nIf you are integrating directly with the REST APIs, rather than via an Atlassian Connect add-on, use one of the\nauthentication methods listed below:\n* [OAuth 2.0](https://developer.atlassian.com/cloud/jira/software/scopes-for-oauth-2-3LO-and-forge-apps/) -\n This token-based method is the recommended method. It is more flexible and secure than other options.\n * [OAuth 1.0a](https://developer.atlassian.com/cloud/jira/platform/jira-rest-api-oauth-authentication) -\n This is a legacy authentication method and, therefore, isn't recommended. Instead use OAuth 2.0.\n * [Basic HTTP](https://developer.atlassian.com/cloud/jira/platform/jira-rest-api-basic-authentication/) -\n This method is only recommended for tools like scripts or bots. It is easier to implement, but much less secure.\n\nNote, Jira itself uses cookie-based authentication in the browser, so you can call REST from Javascript on the page and\nrely on the authentication that the browser has established. To reproduce the behavior of the Jira log-in page (for\nexample, to display authentication error messages to users) can `POST` to the `/auth/1/session` [resource](https://docs.atlassian.com/jira/REST/cloud/#auth/1/session).\n\n### Authentication for on-premises integrations\n\nIf you are integrating an on-premises app with the Jira REST APIs, API calls are authenticated via an OAuth token.\nTo obtain a token, create a set of OAuth credentials with permissions for the APIs that app needs to access.\nUse the credentials to request a token by calling `https://api.atlassian.com/oauth/token`.\nSee [Integrating Jira Software Cloud with on-premises tools](https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/) for details.\nNote that only the [Development Information](#api-group-Development-Information), [Builds](#api-group-Builds), and [Deployments](#api-group-Deployments) APIs are currently available for on-premises integrations.\nTo simplify development, we have a separate [downloadable API spec](https://developer.atlassian.com/cloud/jira/software/on-premise-swagger.json).\n\nAtlassian has developed an [open source plugin for Jenkins](https://github.com/jenkinsci/atlassian-jira-software-cloud-plugin), which you can use to bootstrap development.\nThis plugin uses the authentication method described above and calls the Builds and Deployments APIs.\n\n\n#### Base URL differences\n\nWhen building an on-premises integration, the base URL for API operations is different to the base URL used for Connect apps. This is because requests from on-premises integrations (OAuth) need to be sent via the Atlassian API proxy at `https://api.atlassian.com`.\n\nThis document does not display the base URLs used by on-premises integrations. Therefore, when using an operation, you must replace `https://your-domain.atlassian.net/rest/{type}/{version}/{operation}`\nwith `https://api.atlassian.com/jira/{type}/{version}/cloud/{cloudId}/{operation}`.\n\nFor example:\n* Builds API: Change the path from `https://your-domain.atlassian.net/rest/builds/0.1/bulk` to `https://api.atlassian.com/jira/builds/0.1/cloud/{cloudId}/bulk`.\n* Development Information: Change the path from `https://your-domain.atlassian.net/rest/devinfo/0.10/bulk` to `https://api.atlassian.com/jira/devinfo/0.1/cloud/{cloudId}/bulk`. Note the version change.\n* Deployments: Change the path from `https://your-domain.atlassian.net/rest/deployments/0.1/bulk` to `https://api.atlassian.com/jira/deployments/0.1/cloud/{cloudId}/bulk`.\n\nNote, get the `cloudId` for a Jira instance by calling `https://your-domain.atlassian.net/_edge/tenant_info`.\n\n\n## URI structure\n\nJira Agile's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application\nwill make an HTTP request and parse the response. The Jira Agile REST API uses [JSON](http://en.wikipedia.org/wiki/JSON)\nas its communication format, and the standard HTTP methods like `GET`, `PUT`, `POST` and `DELETE` (see API descriptions\nbelow for which methods are available for each resource). URIs for Jira Agile's REST API resource have the following\nstructure:\n\n http://host:port/context/rest/api-name/api-version/resource-name\n\nCurrently there are two API names available, which will be discussed further below:\n\n * `auth` - for authentication-related operations, and\n * `api` - for everything else.\n\nThe current API version is `1`. However, there is also a symbolic version, called `latest`, which resolves to the\nlatest version supported by the given Jira Software Cloud instance. For example, if you wanted to retrieve the JSON\nrepresentation of a board with `boardId=123`, from a Jira Software Cloud instance at `https://jira.atlassian.net`, you\nwould access:\n\n https://jira.atlassian.net/rest/agile/latest/board/123\n\n## Pagination\n\nPagination is used for the Jira REST APIs to conserve server resources and limit response size for resources that\nreturn potentially large collection of items. A request to a pages API will result in a values array wrapped in a JSON\nobject with some paging metadata, like this:\n\n#### Request\n\n http://host:port/context/rest/api-name/api-version/resource-name?startAt=0&maxResults=10\n\n#### Response\n\n```javascript\n{\n \"startAt\" : 0,\n \"maxResults\" : 10,\n \"total\": 200,\n \"values\": [\n { /* result 0 */ },\n { /* result 1 */ },\n { /* result 2 */ }\n ]\n}\n```\n\n * `startAt` - the item used as the first item in the page of results.\n * `maxResults` - how many results to return per page.\n * `total` - the number of items that the calling user has permissions for. This number *may change* while the client requests the next pages. A client should always assume that the requested page can be empty. REST API consumers should also consider the field to be optional. This value may not be included in the response, if it is too expensive to calculate.\n\nClients can use the `startAt`, `maxResults`, and `total` parameters to retrieve the desired number of results. Note,\neach API resource or method may have a different limit on the number of items returned, which means you can ask for\nmore than you are given. The actual number of items returned is an implementation detail and this can be changed over\ntime.\n\n## Experimental methods\n\nMethods marked as experimental may change without an earlier notice. We are looking for your feedback for these methods.\n\n## Query parameters\n\nAll query parameters for the resources described below are optional, unless specified otherwise.\n\n## Special Request and Response headers\n\n - **X-Atlassian-Token** (request): Operations that accept multipart/form-data must include the `X-Atlassian-Token: no-check` header in requests.\nOtherwise the request will be blocked by XSRF protection.\n- **X-AACCOUNTID** (response): This response header contains the Atlassian account ID of the authenticated user.\n\n## Jira Software field input formats\n\nJira Software provides a number of custom fields, which are made available in the Jira platform REST API. The custom\nfields are: `Sprint`, `Epic link`, `Epic name`, and `Story points`.\n\nYou can read and edit these custom fields via the [issue resource](https://docs.atlassian.com/jira/REST/cloud/#api/2/issue)\nof the Jira Platform REST API. In order to identify the custom field that you want to read or edit, you'll need the\ncustom field id. To obtain the custom field id, retrieve the list of fields from the [fields resource](https://docs.atlassian.com/jira/REST/latest/#api/2/field-getFields)\nand search for the custom field. It's better to find the field based on the schema where possible (e.g. the Sprint\nfield is identified by \"`com.pyxis.greenhopper.jira:gh-sprint`\"), as custom field names are mutable. The custom field\nid will be in the id, (e.g. `id: customfield_10007`).\n\nIf you only need to get the value of the custom field for a single issue, you may want to use the [issue resource](https://docs.atlassian.com/jira-software/REST/cloud/#agile/1.0/issue-getIssue)\nprovided by the Jira Software REST API instead. This resource returns the issue with all Jira Software-specific fields,\nincluding the fields listed above. These fields will also be formatted as proper fields with keys, in the response.\n\nNote, Jira Software also has a number of internal custom fields, which are: `Epic Color`, `Epic Status`, `Flag`, `Rank`.\nThese internal fields shouldn't be read or updated using the REST API and are not documented below.\n\n##### Sprint custom field\n\nThe Sprint custom field contains a list of sprints for a given issue. This list includes the active/future sprint that\nthe issue is currently in, as well as any closed sprints that the issue was in previously.\n\nFor legacy reasons, the [Get issue (Jira platform) method](https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-getIssue)\nreturns the Sprint custom field with sprints in a `toString` format, which is difficult to parse. See the example below.\n\n_**Deprecation notice:** The `toString` representation of sprints in the Sprint custom field that is returned by Get\nissue (Jira platform) will soon be removed. See the [notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-tostring-representation-of-sprints-in-get-issue-response/)._\n\n###### Example - Get issue (Jira platform) response\n\n```javascript\ncustomfield_11458\": [\n \"com.atlassian.greenhopper.service.sprint.Sprint@1bf75fd[id=1,rapidViewId=1,state=CLOSED,name=Sprint 1,goal=Sprint 1 goal,startDate=2016-06-06T21:30:53.537+10:00,endDate=2016-06-20T21:30:00.000+10:00,completeDate=2016-06-06T21:30:57.523+10:00,sequence=1]\",\n \"com.atlassian.greenhopper.service.sprint.Sprint@1689feb[id=2,rapidViewId=1,state=FUTURE,name=Sprint 2,goal=Sprint 2 goal,startDate=,endDate=,completeDate=,sequence=2]\"\n]\n```\n\nIf you want to parse the sprint information, use either the [Get issue (Jira Software) method](https://docs.atlassian.com/jira-software/REST/cloud/#agile/1.0/issue-getIssue)\nor [Get issue (Jira platform) method](https://docs.atlassian.com/jira/REST/cloud/#api/2/issue-getIssue) with expanded\n`versionedRepresentations` instead, both of which return sprints in a proper format. See the example below.\n\n###### Example - Get issue (Jira platform) response with expanded versionedRepresentations\n\n```javascript\n\"customfield_10021\": {\n \"1\": [\n \"com.atlassian.greenhopper.service.sprint.Sprint@1bf75fd[id=1,rapidViewId=1,state=CLOSED,name=Sprint 1,goal=Sprint 1 goal,startDate=2016-06-06T21:30:53.537+10:00,endDate=2016-06-20T21:30:00.000+10:00,completeDate=2016-06-06T21:30:57.523+10:00,sequence=1]\",\n \"com.atlassian.greenhopper.service.sprint.Sprint@1689feb[id=2,rapidViewId=1,state=FUTURE,name=Sprint 2,goal=Sprint 2 goal,startDate=,endDate=,completeDate=,sequence=2]\"\n ],\n \"2\": [\n {\n \"id\": 1,\n \"name\": \"Sprint 1\",\n \"state\": \"closed\",\n \"boardId\": 1\n },\n {\n \"id\": 2,\n \"name\": \"Sprint 2\",\n \"state\": \"future\",\n \"boardId\": 1\n }\n ]\n}\n```\n\nIf you want to update a sprint, you need to know the sprint id, which is a number. See the example below. Note, an\nissue can only be in one active or future sprint at a time, and only the active/future sprint can edited.\n\n###### Example - Update issue request\n\n```javascript\n\"customfield_10021\": 2\n```\n\n##### Epic link custom field\n\nThe Epic link custom field contains the key of an epic that a given issue belongs to. Be aware that only the issue key\nof the existing epic can be set. Also, the Epic link cannot be set for sub-tasks and epics.\n\n###### Example\n\n```javascript\n\"customfield_11458\": \"EPIC-1\"\n```\n\n##### Epic Name\n\nThe Epic name custom field contains the name of an epic that a given issue belongs to. Be aware that only the issue key\nof the existing epic can be set. Also, the epic link cannot be set for sub-tasks and epics.\n\n###### Example\n\n```javascript\n\"customfield_11410\": \"Epic Name\"\n```\n\n##### Estimation\n\nJira Software provides a `Story Points` custom field, however the field is just a regular numeric field. The type of\nestimation and field used for estimation is determined by the board configuration. You can get this from the\n[board configuration resource](https://docs.atlassian.com/jira-software/REST/cloud/#agile/1.0/board-getConfiguration).\nNote that if the estimation field is not on a screen, it cannot be edited, and you should use the\n[Estimate issue for board method](https://docs.atlassian.com/jira-software/REST/cloud/#agile/1.0/issue-estimateIssueForBoard) instead.\n" title: Introduction