The Box Retention Policies API allows creating and managing retention policies that enforce how long content must be kept in Box before it can be deleted, supporting regulatory compliance and information governance requirements.
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.
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/retention-policies-openapi-original.yml