Box Legal Hold Policy Assignments API
The Box Legal Hold Policy Assignments API manages the assignment of legal hold policies to specific users, folders, or files, controlling which content is preserved under legal hold.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Legal Hold Policy Assignments API
description: Needs a description.
paths:
/legal_hold_policy_assignments:
get:
operationId: get_legal_hold_policy_assignments
summary: Box List legal hold policy assignments
tags:
- Legal Hold Policy Assignments
x-box-tag: legal_hold_policy_assignments
description: Retrieves a list of items a legal hold policy has been assigned to.
parameters:
- name: policy_id
description: The ID of the legal hold policy
example: '324432'
in: query
required: true
schema:
type: string
- name: assign_to_type
description: |-
Filters the results by the type of item the
policy was applied to.
example: file
in: query
schema:
type: string
enum:
- file
- file_version
- folder
- user
- name: assign_to_id
description: |-
Filters the results by the ID of item the
policy was applied to.
example: '1234323'
in: query
schema:
type: string
- name: marker
description: >-
Defines the position marker at which to begin returning results.
This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
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
- 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 a list of legal hold policy assignments.
content:
application/json:
schema:
$ref: '#/components/schemas/LegalHoldPolicyAssignments'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
post:
operationId: post_legal_hold_policy_assignments
summary: Box Assign legal hold policy
tags:
- Legal Hold Policy Assignments
x-box-tag: legal_hold_policy_assignments
description: Assign a legal hold to a file, file version, folder, or user.
requestBody:
content:
application/json:
schema:
type: object
required:
- policy_id
- assign_to
properties:
policy_id:
description: The ID of the policy to assign.
example: '123244'
type: string
assign_to:
type: object
description: The item to assign the policy to
required:
- type
- id
properties:
type:
type: string
description: The type of item to assign the policy to
example: folder
enum:
- file
- file_version
- folder
- user
id:
type: string
description: The ID of item to assign the policy to
example: '6564564'
responses:
'201':
description: Returns a new legal hold policy assignment.
content:
application/json:
schema:
$ref: '#/components/schemas/LegalHoldPolicyAssignment'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}:
get:
operationId: get_legal_hold_policy_assignments_id
summary: Box Get legal hold policy assignment
tags:
- Legal Hold Policy Assignments
x-box-tag: legal_hold_policy_assignments
description: Retrieve a legal hold policy assignment.
parameters:
- name: legal_hold_policy_assignment_id
description: The ID of the legal hold policy assignment
example: '753465'
in: path
required: true
schema:
type: string
responses:
'200':
description: Returns a legal hold policy object.
content:
application/json:
schema:
$ref: '#/components/schemas/LegalHoldPolicyAssignment'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
delete:
operationId: delete_legal_hold_policy_assignments_id
x-box-tag: legal_hold_policy_assignments
tags:
- Legal Hold Policy Assignments
summary: Box Unassign legal hold policy
description: |-
Remove a legal hold from an item.
This is an asynchronous process. The policy will not be
fully removed yet when the response returns.
parameters:
- name: legal_hold_policy_assignment_id
description: The ID of the legal hold policy assignment
example: '753465'
in: path
required: true
schema:
type: string
responses:
'202':
description: |-
A blank response is returned if the assignment was
successfully deleted.
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/files_on_hold:
get:
operationId: get_legal_hold_policy_assignments_id_files_on_hold
summary: Box List current file versions for legal hold policy assignment
tags:
- Legal Hold Policy Assignments
x-box-tag: legal_hold_policy_assignments
description: >-
Get a list of current file versions for a legal hold
assignment.
In some cases you may want to get previous file versions instead. In
these
cases, use the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold`
API instead to return any previous versions of a file for this legal
hold
policy assignment.
Due to ongoing re-architecture efforts this API might not return all
file
versions held for this policy ID. Instead, this API will only return the
latest file version held in the newly developed architecture. The `GET
/file_version_legal_holds` API can be used to fetch current and past
versions
of files held within the legacy architecture.
The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used
to
find a list of policy assignments for a given policy ID.
parameters:
- name: legal_hold_policy_assignment_id
description: The ID of the legal hold policy assignment
example: '753465'
in: path
required: true
schema:
type: string
- name: marker
description: >-
Defines the position marker at which to begin returning results.
This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
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
- 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 list of current file versions held under legal hold for
a
specific legal hold policy assignment.
content:
application/json:
schema:
$ref: '#/components/schemas/FileVersionLegalHolds'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/file_versions_on_hold:
get:
operationId: get_legal_hold_policy_assignments_id_file_versions_on_hold
summary: Box List previous file versions for legal hold policy assignment
tags:
- Legal Hold Policy Assignments
x-box-tag: legal_hold_policy_assignments
description: >-
Get a list of previous file versions for a legal hold
assignment.
In some cases you may only need the latest file versions instead. In
these
cases, use the `GET /legal_hold_policy_assignments/:id/files_on_hold`
API
instead to return any current (latest) versions of a file for this legal
hold
policy assignment.
Due to ongoing re-architecture efforts this API might not return all
files
held for this policy ID. Instead, this API will only return past file
versions
held in the newly developed architecture. The `GET
/file_version_legal_holds`
API can be used to fetch current and past versions of files held within
the
legacy architecture.
The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used
to
find a list of policy assignments for a given policy ID.
parameters:
- name: legal_hold_policy_assignment_id
description: The ID of the legal hold policy assignment
example: '753465'
in: path
required: true
schema:
type: string
- name: marker
description: >-
Defines the position marker at which to begin returning results.
This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
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
- 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 list of previous file versions held under legal hold for
a
specific legal hold policy assignment.
content:
application/json:
schema:
$ref: '#/components/schemas/FileVersionLegalHolds'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
LegalHoldPolicyAssignments:
title: Legal hold policy assignments
type: object
x-box-resource-id: legal_hold_policy_assignments
x-box-tag: legal_hold_policy_assignments
description: A list of legal hold policies assignments.
allOf:
- 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
prev_marker:
description: The marker for the start of the previous page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih
type: string
nullable: true
- properties:
entries:
type: array
description: |-
A list of legal hold
policy assignments
items:
$ref: '#/components/schemas/LegalHoldPolicyAssignment'
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
LegalHoldPolicyAssignment:
title: Legal hold policy assignment
type: object
x-box-resource-id: legal_hold_policy_assignment
x-box-tag: legal_hold_policy_assignments
description: |-
Legal Hold Assignments are used to assign Legal Hold
Policies to Users, Folders, Files, or File Versions.
Creating a Legal Hold Assignment puts a hold
on the File-Versions that belong to the Assignment's
'apply-to' entity.
allOf:
- $ref: '#/components/schemas/LegalHoldPolicyAssignment--Base'
- properties:
legal_hold_policy:
allOf:
- $ref: '#/components/schemas/LegalHoldPolicy--Mini'
- description: |-
The policy that the legal hold policy assignment
is part of
assigned_to:
allOf:
- oneOf:
- $ref: '#/components/schemas/File'
- $ref: '#/components/schemas/Folder'
- $ref: '#/components/schemas/WebLink'
- description: |-
The item that the the legal hold policy
is assigned to. Includes type and ID.
assigned_by:
allOf:
- $ref: '#/components/schemas/User--Mini'
- description: |-
The user who created the legal hold policy
assignment
assigned_at:
type: string
format: date-time
description: |-
When the legal hold policy assignment object was
created
example: '2012-12-12T10:53:43-08:00'
deleted_at:
type: string
format: date-time
description: |-
When the assignment release request was sent.
(Because it can take time for an assignment to fully
delete, this isn't quite the same time that the
assignment is fully deleted). If null, Assignment
was not deleted.
example: '2012-12-12T10:53:43-08:00'
FileVersionLegalHolds:
title: File version legal holds
type: object
x-box-resource-id: file_version_legal_holds
x-box-tag: file_version_legal_holds
description: A list of file version legal holds.
allOf:
- 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
prev_marker:
description: The marker for the start of the previous page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih
type: string
nullable: true
- properties:
entries:
type: array
description: A list of file version legal holds
items:
$ref: '#/components/schemas/FileVersionLegalHold'
tags:
- name: Legal Hold Policy Assignments