openapi: 3.1.0 info: title: Box File Version Retentions API description: Needs a description. paths: /file_version_retentions: get: operationId: get_file_version_retentions tags: - File Version Retentions x-box-tag: file_version_retentions summary: Box List file version retentions description: Retrieves all file version retentions for the given enterprise. parameters: - name: file_id description: Filters results by files with this ID. in: query example: '43123123' required: false schema: type: string - name: file_version_id description: Filters results by file versions with this ID. in: query example: '1' required: false schema: type: string - name: policy_id description: Filters results by the retention policy with this ID. in: query required: false example: '982312' schema: type: string - name: disposition_action description: |- Filters results by the retention policy with this disposition action. in: query required: false example: permanently_delete schema: type: string enum: - permanently_delete - remove_retention - name: disposition_before description: |- Filters results by files that will have their disposition come into effect before this date. in: query required: false example: '2012-12-12T10:53:43-08:00' schema: type: string - name: disposition_after description: |- Filters results by files that will have their disposition come into effect after this date. in: query required: false example: '2012-12-19T10:34:23-08:00' 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: 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 responses: '200': description: Returns a list of all file version retentions for the enterprise. content: application/json: schema: $ref: '#/components/schemas/FileVersionRetentions' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /file_version_retentions/{file_version_retention_id}: get: operationId: get_file_version_retentions_id tags: - File Version Retentions x-box-tag: file_version_retentions summary: Box Get retention on file description: Returns information about a file version retention. parameters: - name: file_version_retention_id description: The ID of the file version retention in: path required: true example: '3424234' schema: type: string responses: '200': description: Returns a file version retention object. content: application/json: schema: $ref: '#/components/schemas/FileVersionRetention' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' components: schemas: FileVersionRetentions: title: File version retentions type: object x-box-resource-id: file_version_retentions x-box-tag: file_version_retentions description: A list of file version retentions. 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 retentions items: $ref: '#/components/schemas/FileVersionRetention' 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 FileVersionRetention: title: File version retention type: object x-box-resource-id: file_version_retention x-box-tag: file_version_retentions description: |- A retention policy blocks permanent deletion of content for a specified amount of time. Admins can apply policies to specified folders, or an entire enterprise. A file version retention is a record for a retained file version. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. For more information about retention policies, please visit our help documentation properties: id: type: string description: The unique identifier for this file version retention. example: '11446498' type: type: string description: '`file_version_retention`' example: file_version_retention enum: - file_version_retention file_version: allOf: - $ref: '#/components/schemas/FileVersion--Mini' - description: |- The file version this file version retention was applied to file: allOf: - $ref: '#/components/schemas/File--Mini' - description: The file this file version retention was applied to applied_at: type: string format: date-time description: |- When this file version retention object was created example: '2012-12-12T10:53:43-08:00' disposition_at: type: string format: date-time description: |- When the retention expires on this file version retention example: '2012-12-12T10:53:43-08:00' winning_retention_policy: allOf: - $ref: '#/components/schemas/RetentionPolicy--Mini' - description: |- The winning retention policy applied to this file version retention. A file version can have multiple retention policies applied. tags: - name: File Version Retentions