openapi: 3.1.0 info: title: Box Retention Policies API description: Needs a description. paths: /retention_policies: get: operationId: get_retention_policies summary: Box List retention policies tags: - Retention Policies x-box-tag: retention_policies description: Retrieves all of the retention policies for an enterprise. parameters: - name: policy_name description: |- Filters results by a case sensitive prefix of the name of retention policies. in: query required: false example: Sales Policy schema: type: string - name: policy_type description: Filters results by the type of retention policy. in: query required: false example: finite schema: type: string enum: - finite - indefinite - name: created_by_user_id description: Filters results by the ID of the user who created policy. example: '21312321' in: query required: false schema: type: string - name: fields description: |- A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. in: query example: - id - type - name required: false explode: false schema: type: array items: type: string - name: limit description: The maximum number of items to return per page. in: query required: false example: 1000 schema: type: integer format: int64 maximum: 1000 - name: marker description: >- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. in: query required: false example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii schema: type: string responses: '200': description: Returns a list retention policies in the enterprise. content: application/json: schema: $ref: '#/components/schemas/RetentionPolicies' '400': description: >- Returns a `bad_request` if a non existent `policy_type` was specified. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: >- Returns a `not_found` error if the user specified in `created_by_user_id` does not exist. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' post: operationId: post_retention_policies summary: Box Create retention policy tags: - Retention Policies x-box-tag: retention_policies description: Creates a retention policy. requestBody: content: application/json: schema: type: object required: - policy_name - policy_type - disposition_action properties: policy_name: type: string description: The name for the retention policy example: Some Policy Name description: type: string description: The additional text description of the retention policy. example: Policy to retain all reports for at least one month policy_type: type: string example: finite description: |- The type of the retention policy. A retention policy type can either be `finite`, where a specific amount of time to retain the content is known upfront, or `indefinite`, where the amount of time to retain the content is still unknown. enum: - finite - indefinite disposition_action: type: string example: permanently_delete description: |- The disposition action of the retention policy. `permanently_delete` deletes the content retained by the policy permanently. `remove_retention` lifts retention policy from the content, allowing it to be deleted by users once the retention policy has expired. enum: - permanently_delete - remove_retention retention_length: oneOf: - type: string format: int32 nullable: true - type: number format: int32 nullable: false example: '365' description: |- The length of the retention policy. This value specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has a `policy_type` of `indefinite`, the `retention_length` will also be `indefinite`. retention_type: type: string example: modifiable description: >- Specifies the retention type: * `modifiable`: You can modify the retention policy. For example, you can add or remove folders, shorten or lengthen the policy duration, or delete the assignment. Use this type if your retention policy is not related to any regulatory purposes. * `non_modifiable`: You can modify the retention policy only in a limited way: add a folder, lengthen the duration, retire the policy, change the disposition action or notification settings. You cannot perform other actions, such as deleting the assignment or shortening the policy duration. Use this type to ensure compliance with regulatory retention policies. enum: - modifiable - non_modifiable can_owner_extend_retention: type: boolean enum: - true - false example: true description: |- Whether the owner of a file will be allowed to extend the retention. are_owners_notified: type: boolean enum: - true - false example: true description: |- Whether owner and co-owners of a file are notified when the policy nears expiration. custom_notification_recipients: type: array description: |- A list of users notified when the retention policy duration is about to end. items: $ref: '#/components/schemas/User--Mini' responses: '201': description: Returns a new retention policy object. content: application/json: schema: $ref: '#/components/schemas/RetentionPolicy' '400': description: >- Returns a `bad_request` error with the `retention_length` was specified for a `infinite` retention policy, an incorrect `disposition_action` was set, or description exceeds maximum length of 500 characters. content: application/json: schema: $ref: '#/components/schemas/ClientError' '409': description: >- Returns an error if a retention policy with the given name already exists content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /retention_policies/{retention_policy_id}: get: operationId: get_retention_policies_id summary: Box Get retention policy tags: - Retention Policies x-box-tag: retention_policies description: Retrieves a retention policy. parameters: - name: retention_policy_id description: The ID of the retention policy. example: '982312' in: path required: true schema: type: string - name: fields description: |- A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. in: query example: - id - type - name required: false explode: false schema: type: array items: type: string responses: '200': description: Returns the retention policy object. content: application/json: schema: $ref: '#/components/schemas/RetentionPolicy' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' put: operationId: put_retention_policies_id summary: Box Update retention policy tags: - Retention Policies x-box-tag: retention_policies description: Updates a retention policy. parameters: - name: retention_policy_id description: The ID of the retention policy. example: '982312' in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: policy_name: type: string description: The name for the retention policy example: Some Policy Name nullable: true description: type: string description: The additional text description of the retention policy. example: Policy to retain all reports for at least one month nullable: true disposition_action: anyOf: - type: string enum: - permanently_delete - remove_retention - type: string pattern: .^ nullable: true description: >- The disposition action of the retention policy. This action can be `permanently_delete`, which will cause the content retained by the policy to be permanently deleted, or `remove_retention`, which will lift the retention policy from the content, allowing it to be deleted by users, once the retention policy has expired. You can use "null" if you don't want to change `disposition_action`. example: permanently_delete retention_type: type: string example: non-modifiable nullable: true description: >- Specifies the retention type: * `modifiable`: You can modify the retention policy. For example, you can add or remove folders, shorten or lengthen the policy duration, or delete the assignment. Use this type if your retention policy is not related to any regulatory purposes. * `non-modifiable`: You can modify the retention policy only in a limited way: add a folder, lengthen the duration, retire the policy, change the disposition action or notification settings. You cannot perform other actions, such as deleting the assignment or shortening the policy duration. Use this type to ensure compliance with regulatory retention policies. When updating a retention policy, you can use `non-modifiable` type only. You can convert a `modifiable` policy to `non-modifiable`, but not the other way around. retention_length: oneOf: - type: string format: int32 nullable: true - type: number format: int32 nullable: false example: '365' description: |- The length of the retention policy. This value specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has a `policy_type` of `indefinite`, the `retention_length` will also be `indefinite`. status: type: string example: retired nullable: true description: |- Used to retire a retention policy. If not retiring a policy, do not include this parameter or set it to `null`. can_owner_extend_retention: type: boolean nullable: true description: |- Determines if the owner of items under the policy can extend the retention when the original retention duration is about to end. example: false are_owners_notified: type: boolean nullable: true description: |- Determines if owners and co-owners of items under the policy are notified when the retention duration is about to end. example: false custom_notification_recipients: type: array nullable: true description: >- A list of users notified when the retention duration is about to end. items: $ref: '#/components/schemas/User--Base' responses: '200': description: Returns the updated retention policy object. content: application/json: schema: $ref: '#/components/schemas/RetentionPolicy' '400': description: >- Returns a `bad_request` if an incorrect `disposition_action` was set or description exceeds maximum length of 500 characters. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: |- Returns an error when a user wants to shorten the duration of a non-modifiable policy, or to convert a non-modifiable policy to a modifiable one. Note: Lengthening policy duration is allowed. content: application/json: schema: $ref: '#/components/schemas/ClientError' '409': description: >- Returns an error if a retention policy with the given name already exists content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' delete: operationId: delete_retention_policies_id summary: Box Delete retention policy tags: - Retention Policies x-box-tag: retention_policies description: Permanently deletes a retention policy. parameters: - name: retention_policy_id description: The ID of the retention policy. example: '982312' in: path required: true schema: type: string responses: '204': description: Returns an empty response when the policy has been deleted. '403': description: |- Returns an error if the policy is non-modifiable or the user does not have the required access to perform the action. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: Returns an error if the policy is not found. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /retention_policies/{retention_policy_id}/assignments: get: operationId: get_retention_policies_id_assignments summary: Box List retention policy assignments tags: - Retention Policies x-box-tag: retention_policy_assignments description: >- Returns a list of all retention policy assignments associated with a specified retention policy. parameters: - name: retention_policy_id description: The ID of the retention policy. example: '982312' in: path required: true schema: type: string - name: type description: The type of the retention policy assignment to retrieve. in: query required: false example: metadata_template schema: type: string enum: - folder - enterprise - metadata_template - name: fields description: |- A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. in: query example: - id - type - name required: false explode: false schema: type: array items: type: string - name: marker description: >- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. in: query required: false example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii schema: type: string - name: limit description: The maximum number of items to return per page. in: query required: false example: 1000 schema: type: integer format: int64 maximum: 1000 responses: '200': description: >- Returns a list of the retention policy assignments associated with the specified retention policy. content: application/json: schema: $ref: '#/components/schemas/RetentionPolicyAssignments' '400': description: Returns an error if an unknown `type` is specified. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' components: schemas: RetentionPolicies: title: Retention policies type: object x-box-resource-id: retention_policies x-box-tag: retention_policies description: A list of retention policies. allOf: - properties: entries: description: A list in which each entry represents a retention policy object. type: array items: $ref: '#/components/schemas/RetentionPolicy' - type: object description: |- The part of an API response that describes marker based pagination properties: limit: description: >- The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. example: 1000 type: integer format: int64 next_marker: description: The marker for the start of the next page of results. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii type: string nullable: true ClientError: title: Client error type: object x-box-resource-id: client_error description: A generic error properties: type: description: error example: error type: string enum: - error nullable: false status: description: The HTTP status of the response. example: 400 type: integer format: int32 nullable: false code: description: A Box-specific error code example: item_name_invalid type: string enum: - created - accepted - no_content - redirect - not_modified - bad_request - unauthorized - forbidden - not_found - method_not_allowed - conflict - precondition_failed - too_many_requests - internal_server_error - unavailable - item_name_invalid - insufficient_scope message: description: A short message describing the error. example: Method Not Allowed type: string nullable: false context_info: description: |- A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example. type: object nullable: true properties: message: type: string description: More details on the error. example: Something went wrong. help_url: description: A URL that links to more information about why this error occurred. example: >- https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/ type: string nullable: false request_id: description: |- A unique identifier for this response, which can be used when contacting Box support. type: string example: abcdef123456 nullable: false RetentionPolicy: title: Retention policy type: object x-box-resource-id: retention_policy x-box-tag: retention_policies x-box-variant: standard description: |- A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then later assign them to specific folders, metadata templates, or their entire enterprise. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. allOf: - $ref: '#/components/schemas/RetentionPolicy--Mini' - properties: description: type: string example: Policy to retain all reports for at least one month description: The additional text description of the retention policy. policy_type: type: string example: finite description: |- The type of the retention policy. A retention policy type can either be `finite`, where a specific amount of time to retain the content is known upfront, or `indefinite`, where the amount of time to retain the content is still unknown. enum: - finite - indefinite retention_type: type: string example: non_modifiable description: >- Specifies the retention type: * `modifiable`: You can modify the retention policy. For example, you can add or remove folders, shorten or lengthen the policy duration, or delete the assignment. Use this type if your retention policy is not related to any regulatory purposes. * `non-modifiable`: You can modify the retention policy only in a limited way: add a folder, lengthen the duration, retire the policy, change the disposition action or notification settings. You cannot perform other actions, such as deleting the assignment or shortening the policy duration. Use this type to ensure compliance with regulatory retention policies. enum: - modifiable - non_modifiable status: type: string example: active description: |- The status of the retention policy. The status of a policy will be `active`, unless explicitly retired by an administrator, in which case the status will be `retired`. Once a policy has been retired, it cannot become active again. enum: - active - retired created_by: allOf: - $ref: '#/components/schemas/User--Mini' - description: |- A mini user object representing the user that created the retention policy. created_at: type: string format: date-time description: When the retention policy object was created. example: '2012-12-12T10:53:43-08:00' modified_at: type: string format: date-time description: When the retention policy object was last modified. example: '2012-12-12T10:53:43-08:00' can_owner_extend_retention: type: boolean description: |- Determines if the owner of items under the policy can extend the retention when the original retention duration is about to end. example: false are_owners_notified: type: boolean description: |- Determines if owners and co-owners of items under the policy are notified when the retention duration is about to end. example: false custom_notification_recipients: type: array description: >- A list of users notified when the retention policy duration is about to end. items: $ref: '#/components/schemas/User--Mini' assignment_counts: type: object description: Counts the retention policy assignments for each item type. properties: enterprise: description: >- The number of enterprise assignments this policy has. The maximum value is 1. format: int64 type: integer example: 1 folder: description: The number of folder assignments this policy has. format: int64 type: integer example: 1 metadata_template: description: The number of metadata template assignments this policy has. format: int64 type: integer example: 1 RetentionPolicyAssignments: title: Retention policy assignments type: object x-box-resource-id: retention_policy_assignments x-box-tag: retention_policy_assignments description: A list of retention policy assignments. allOf: - properties: entries: type: array description: A list of retention policy assignments items: $ref: '#/components/schemas/RetentionPolicyAssignment' - type: object description: |- The part of an API response that describes marker based pagination properties: limit: description: >- The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. example: 1000 type: integer format: int64 next_marker: description: The marker for the start of the next page of results. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii type: string nullable: true tags: - name: Retention Policies