The Box File Version Legal Holds API provides information about file versions currently under legal hold, enabling applications to list and retrieve details about held file versions and their associated legal hold policies.
openapi: 3.1.0
info:
title: Box File Version Legal Holds API
description: Needs a description.
paths:
/file_version_legal_holds/{file_version_legal_hold_id}:
get:
operationId: get_file_version_legal_holds_id
summary: Box Get file version legal hold
tags:
- File Version Legal Holds
x-box-tag: file_version_legal_holds
description: |-
Retrieves information about the legal hold policies
assigned to a file version.
parameters:
- name: file_version_legal_hold_id
description: The ID of the file version legal hold
in: path
required: true
example: '2348213'
schema:
type: string
responses:
'200':
description: Returns the legal hold policy assignments for the file version.
content:
application/json:
schema:
$ref: '#/components/schemas/FileVersionLegalHold'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/file_version_legal_holds:
get:
operationId: get_file_version_legal_holds
summary: Box List file version legal holds
tags:
- File Version Legal Holds
x-box-tag: file_version_legal_holds
description: >-
Get a list of file versions on legal hold for a legal hold
assignment.
Due to ongoing re-architecture efforts this API might not return all
file
versions for this policy ID.
Instead, this API will only return file versions held in the legacy
architecture. Two new endpoints will available to request any file
versions
held in the new architecture.
For file versions held in the new architecture, the `GET
/legal_hold_policy_assignments/:id/file_versions_on_hold` API can be
used to
return all past file versions available for this policy assignment, and
the
`GET /legal_hold_policy_assignments/:id/files_on_hold` API can be used
to
return any current (latest) versions of a file under legal hold.
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.
Once the re-architecture is completed this API will be deprecated.
parameters:
- name: policy_id
description: |-
The ID of the legal hold policy to get the file version legal
holds for.
in: query
example: '133870'
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
responses:
'200':
description: |-
Returns the list of file version legal holds for a specific legal
hold policy.
content:
application/json:
schema:
$ref: '#/components/schemas/FileVersionLegalHolds'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
FileVersionLegalHold:
title: File version legal hold
type: object
x-box-resource-id: file_version_legal_hold
x-box-tag: file_version_legal_holds
description: |-
File-Version-Legal-Hold is an entity representing all
holds on a File Version.
properties:
id:
type: string
description: The unique identifier for this file version legal hold
example: '11446498'
type:
type: string
description: '`file_version_legal_hold`'
example: file_version_legal_hold
enum:
- file_version_legal_hold
file_version:
allOf:
- $ref: '#/components/schemas/FileVersion--Mini'
- description: The file version that is held
file:
allOf:
- $ref: '#/components/schemas/File--Mini'
- description: |-
The file for the file version held.
Note that there is no guarantee that the current
version of this file is held.
legal_hold_policy_assignments:
description: List of assignments contributing to this Hold.
type: array
items:
$ref: '#/components/schemas/LegalHoldPolicyAssignment'
deleted_at:
type: string
format: date-time
description: |-
Time that this File-Version-Legal-Hold was
deleted.
example: '2012-12-12T10:53:43-08:00'
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
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: File Version Legal Holds