{"openapi":"3.0.3","info":{"title":"Data Loss Prevention","version":"1.0.0"},"servers":[{"url":"https://api.atlassian.com/admin/dlp/v1/","description":"Atlassian API endpoint"}],"tags":[{"name":"Classification Level","description":"Classification Level APIs\""}],"paths":{"/orgs/{orgId}/classification-levels":{"post":{"tags":["Classification Level"],"summary":"Create a new classification level","description":"Creates a draft [classification level](cloud/admin/dlp/rest/intro/#classification%20level) for an organization.","operationId":"createLevel","x-experimental":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLevelModel"}}}},"parameters":[{"in":"path","name":"orgId","schema":{"type":"string"},"description":"Your organization is identified by a Unique ID. You get your organization ID and Organization API key simultaneously.","required":true}],"responses":{"202":{"description":"Returned if operation is successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Level"}}}},"400":{"description":"Returned if request is not in correct format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Returned if the Organization does not have this paid feature enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Returned if the user does not have correct permission to create this classification level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Classification Level"],"summary":"Get all classification levels by orgId","description":"Gets all [classification levels](/cloud/admin/dlp/rest/intro/#classification%20level) in an organization.","operationId":"getLevelList","x-experimental":true,"parameters":[{"in":"path","name":"orgId","schema":{"type":"string"},"description":"Your organization is identified by a Unique ID. You get your organization ID and Organization API key simultaneously.","required":true}],"responses":{"200":{"description":"Returned if the request is successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LevelList"}}}},"400":{"description":"Returned if request is not in correct format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Returned if the user does not have correct permission to read the classification levels.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orgs/{orgId}/classification-levels/{levelId}":{"get":{"tags":["Classification Level"],"summary":"Get a classification level","description":"Gets a [classification level](/cloud/admin/dlp/rest/intro/#classification%20level) with the supplied levelId.","operationId":"getLevel","x-experimental":true,"parameters":[{"in":"path","name":"levelId","description":"Unique ID associated with the classification level obtained during its creation.","schema":{"type":"string"},"required":true},{"in":"path","name":"orgId","schema":{"type":"string"},"description":"Your organization is identified by a Unique ID. You get your organization ID and Organization API key simultaneously.","required":true}],"responses":{"200":{"description":"Returned if the request is successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Level"}}}},"400":{"description":"Returned if request is not in correct format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Returned if the user does not have correct permission to read the classification levels.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Returned if the classification level is not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Classification Level"],"summary":"Edit a classification level","description":"Edits a [classification level](/cloud/admin/dlp/rest/intro/#classification%20level) with the supplied levelId.","operationId":"editLevel","x-experimental":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLevelModel"}}}},"parameters":[{"in":"path","name":"levelId","description":"Unique ID associated with the classification level, obtained during its creation.","schema":{"type":"string"},"required":true},{"in":"path","name":"orgId","schema":{"type":"string"},"description":"Your organization is identified by a Unique ID. You get your organization ID and Organization API key simultaneously.","required":true}],"responses":{"202":{"description":"Returned if the request is accepted."},"400":{"description":"Returned if request is not in correct format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Returned if the user does not have correct permission to read this classification level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Returned if the classification level is not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orgs/{orgId}/classification-levels/publish":{"post":{"tags":["Classification Level"],"summary":"Publish classification level(s)","description":"Publishes one or more [classification level](/cloud/admin/dlp/rest/intro/#classification%20level) with the supplied levelIds.","operationId":"publishLevel","x-experimental":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LevelIdList"}}}},"parameters":[{"in":"path","name":"orgId","schema":{"type":"string"},"description":"Your organization is identified by a Unique ID. You get your organization ID and Organization API key simultaneously.","required":true}],"responses":{"202":{"description":"Returned if the request is accepted."},"400":{"description":"Returned if request is not in correct format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Returned if the user does not have correct permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Returned if the classification level is not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Returned for logic errors including moving from current status to requested status is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orgs/{orgId}/classification-levels/archive":{"post":{"tags":["Classification Level"],"summary":"Archive a data classification level","description":"Archives a [classification level](/cloud/admin/dlp/rest/intro/#classification%20level) with the supplied levelId (batch not currently supported).\n When you archive a published classification level:\n - Users won’t be able to classify pages at this level\n - Any page or issues classified at this level will become unclassified\n - Pages and issues will retain history\n\nIn the event that the classification level is restored and published, those pages and issues will regain this classification level.","operationId":"archiveLevel","x-experimental":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LevelIdList"}}}},"parameters":[{"in":"path","name":"orgId","schema":{"type":"string"},"description":"Your organization is identified by a Unique ID. You get your organization ID and Organization API key simultaneously.","required":true}],"responses":{"202":{"description":"Returned if the request is accepted."},"400":{"description":"Returned if request is not in correct format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Returned if the user does not have correct permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Returned if the classification level is not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Returned for logic errors including moving from current status to requested status is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orgs/{orgId}/classification-levels/restore":{"post":{"tags":["Classification Level"],"summary":"Restore a classification level","description":"Restores a [classification level](/cloud/admin/dlp/rest/intro/#classification%20level) with supplied levelId. When you restore an archived classification level, it’s restored as a draft. \n\nWhen you’re ready for your users to start classifying Confluence pages and Jira issues, you can publish the classification level.\n\nIf the classification level had been published before being archived, restored, and published again, any pages and issues classified at this level before it was archived will regain this classification level.","operationId":"restoreLevel","x-experimental":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LevelIdList"}}}},"parameters":[{"in":"path","name":"orgId","schema":{"type":"string"},"description":"Your organization is identified by a Unique ID. You get your organization ID and Organization API key simultaneously.","required":true}],"responses":{"202":{"description":"Returned if the request is accepted."},"400":{"description":"Returned if request is not in correct format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Returned if the user does not have correct permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Returned if the classification level is not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Returned for logic errors including moving from current status to requested status is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orgs/{orgId}/classification-levels/reorder":{"post":{"tags":["Classification Level"],"summary":"Reorder classification levels","description":"Changes the order of [classification levels](/cloud/admin/dlp/rest/intro/#classification%20level). The most sensitive classification level should be ranked 1.","operationId":"reorder","x-experimental":true,"requestBody":{"description":"Map<LevelId, Sensitivity>\n\nKey value pair of levelId to sensitivity number\n","required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["requestedOrder"],"properties":{"requestedOrder":{"type":"object","additionalProperties":{"type":"number"}}},"example":{"requestedOrder":{"ari:cloud:platform::classification-tag/3c3e607b-9e26-4df5-9c4f-bd09dc74404b":1,"ari:cloud:platform::classification-tag/571724a1-8ff7-4f53-acb4-b3480338307e":2}}}}}},"parameters":[{"in":"path","name":"orgId","schema":{"type":"string"},"description":"Your organization is identified by a Unique ID. You get your organization ID and Organization API key simultaneously.","required":true}],"responses":{"202":{"description":"Returned if the request is accepted."},"400":{"description":"Returned if request is not in correct format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Returned if the user does not have correct permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Returned if the org is not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Returned for logic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"x-atlassian-narrative":{"documents":[{"title":"About","anchor":"About","body":"\n**These APIs are available to Atlassian Information Security Beta early access program customers only. The development, release, and timing of any features or functionality described herein remain at the sole discretion of Atlassian and is subject to change. If you’re not part of the program, subscribe to our [Cloud roadmap](https://www.atlassian.com/roadmap/cloud) to be informed about newly released and upcoming features.**\n\n\nThe data loss prevention (DLP) REST APIs are:\n- Designed to empower organizations in identifying and preventing inadvertent sharing, transfer, or unauthorized use of sensitive data.\n- Comprehensive set of APIs extending capabilities to monitor and safeguard sensitive data.\n- Capable of operating across various Atlassian products.\n- Ensures a unified and secure environment for data protection within the organization."},{"title":"Data classification","anchor":"Data classification","body":"Data classification is the process of identifying and categorizing data in an organization. Utilizing classification level APIs can support your organization's internal data governance by allowing you to apply various labels to your data. For example, you can create classifications based on data sensitivity, or classifications based on regulatory requirements that may apply to your organization. The choice of classification label depends on the specific requirements of your organization. Employing classification level APIs can help in establishing and enforcing rules and expectations concerning the creation, storage, management, movement, or deletion of data, both within and outside the organization.\n\n**Data classification in Atlassian products**\n\nThis feature will let you categorize data within Jira and Confluence and align it with your organization's established data classification policy. It is not possible to create distinct classification levels for individual products. Once established, these classification levels will apply across Confluence and Jira. Content assigned a classification level will display a corresponding classification badge."},{"title":"Classification level","anchor":"Classification level","body":"Classification level is a unit of data classification defined by your organization and and will be associated with specific data handling requirements (e.g. storage) that you set. For example, you can create classification levels based on your internal company policies. Classification levels will apply across your organization, which means it’s not possible to create different classification levels for separate products. There are several details of a classification level you can customize to reflect your company’s expectations.\n<table>\n    <thead>\n  <tr>\n    <th>Detail</th>\n    <th>Explanation</th>\n  </tr>\n  </thead>\n  <tbody>\n      <tr>\n        <td>Name</td>\n        <td>What the classification level is known as, for example, Confidential.</td>\n      </tr>\n      <tr>\n        <td>Definition</td>\n        <td>A user-facing description of the types of data that fall under this classification level.</td>\n      </tr>\n      <tr>\n        <td>Color</td>\n        <td>The color of the classification level badge displayed on a page or issue when it’s classified at this level.</td>\n      </tr>\n      <tr>\n        <td>Guidelines</td>\n        <td>A user-facing explanation of any rules and expectations around using, moving, or storing data classified at this level.</td>\n      </tr>\n      <tr>\n        <td>Sensitivity</td>\n        <td>A rank that determines the order in which classification levels are displayed. The most sensitive classification level should be ranked 1.</td>\n      </tr>\n  </tbody>\n</table>\n\nYou can create up to 10 classification levels. If you need to create more, archive a classification level to create another one. \n\nClassification levels are always created and saved as drafts. When you’re ready for your users to start classifying Confluence pages or Jira issues, you can publish your classification levels."},{"title":"Authentication","anchor":"auth","body":"Authentication is implemented via an API key. Use the API Key as a Bearer access token to authenticate the script and manage your organization. The Organization ID is used as a unique identifier in the path parameter for the organization. Copy the Organization ID and API key and keep them in a secure place. We won’t show them to you again.\n\nTo make requests to the API with the client/tool of your choice, [Create an API key and get the organization ID](https://support.atlassian.com/organization-administration/docs/manage-an-organization-with-the-admin-apis/)."},{"title":"Rate limits","anchor":"rate limits","body":"A rate limit defines the maximum number of API calls an application or user can perform during a specific time frame. When this threshold is surpassed, or if CPU or total time constraints are exceeded, the application or user might encounter delays. Consequently, API requests initiated by the user or application will not succeed.\n\nIt is essential to note that all API requests are subjected to rate limits.\n\nWhen a client breach the rate limit thresholds, they get [HTTP 429 Too Many Requests](https://datatracker.ietf.org/doc/html/rfc6585#section-4) responses. The client has to wait for the rate limit counter to reset on the server before being able to make successful requests.\n\n**Rate limit response headers**\n\nThe following HTTP response headers are returned indicating the rate and threshold allowed for a client for each endpoint.\n- **X-RateLimit-Limit:** The number of allowed requests in the current period\n- **X-RateLimit-Remaining:** The number of remaining requests in the current period\n- **X-RateLimit-Reset:** Next period reset time (ISO 8601 - Date and time in UTC)"},{"title":"Version and URI","anchor":"uri","body":"\nThe URIs for resources have the following structure:\n\n```\nhttps://api.atlassian.com/admin/<version>/dlp/<resource-name>\n```"},{"title":"Pagination","anchor":"Pagination","body":"\nThe DLP REST API uses pagination to conserve server resources and limit response size. If there are more results available after the current page, a link to the next page of results is included in the JSON. You can use the `cursor` parameter to set a specific starting point for the results."},{"title":"Experimental features","anchor":"Experimental features","body":"\nMethods marked as experimental may change without an earlier notice. We are looking for your feedback for these methods."},{"title":"Vocabulary","anchor":"Vocabulary","body":"\nThere are several concepts that are common ideas with a unique meaning in Atlassian Administration. Learn more about [terminology](https://developer.atlassian.com/cloud/admin/cloud-admin-vocabulary/) related to the cloud admin experience."}]},"components":{"schemas":{"Level":{"type":"object","required":["name","levelId","orgId","sensitivity","status"],"properties":{"levelId":{"type":"string"},"orgId":{"type":"string"},"name":{"type":"string"},"definition":{"type":"string"},"guideline":{"type":"string"},"color":{"$ref":"#/components/schemas/LevelColor"},"sensitivity":{"type":"number","minimum":1,"maximum":10},"status":{"$ref":"#/components/schemas/LevelStatus"},"createdBy":{"$ref":"#/components/schemas/User"},"createdOn":{"type":"string","format":"date-time"},"changedBy":{"$ref":"#/components/schemas/User"},"changedOn":{"type":"string","format":"date-time"}}},"CreateLevelModel":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"What the classification level is known as, for example, Confidential."},"definition":{"type":"string","description":"A user-facing description of the types of data that fall under this classification level."},"guideline":{"type":"string","description":"A user-facing explanation of any rules and expectations around using, moving, or storing data classified at a level."},"color":{"$ref":"#/components/schemas/LevelColor"}}},"UpdateLevelModel":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"What the classification level is known as, for example, Confidential."},"definition":{"type":"string","description":"A user-facing description of the types of data that fall under this classification level."},"guideline":{"type":"string","description":"A user-facing explanation of any rules and expectations around using, moving, or storing data classified at a level."},"color":{"$ref":"#/components/schemas/LevelColor"}}},"Error":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"status":{"type":"string"},"code":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}},"LevelList":{"type":"object","properties":{"levels":{"type":"array","items":{"$ref":"#/components/schemas/Level"}},"links":{"$ref":"#/components/schemas/Links"}}},"LevelColor":{"type":"string","description":"The color of the classification level badge displayed on a page or issue when it’s classified at this level.","enum":["RED","RED_BOLD","ORANGE","YELLOW","GREEN","BLUE","BLUE_BOLD","TEAL","PURPLE","GREY","NONE"]},"LevelStatus":{"type":"string","enum":["Published","Archived","Draft"]},"LevelIdList":{"type":"object","required":["levelId"],"properties":{"levelIds":{"type":"array","description":"Unique ID associated with the classification level, obtained during its creation.","items":{"type":"string"},"minItems":1}}},"Links":{"type":"object","properties":{"first":{"type":"string"},"next":{"type":"string"},"prev":{"type":"string"}}},"User":{"type":"object","required":["accountId"],"properties":{"name":{"type":"string"},"accountId":{"type":"string"}}}}}}