Box Collections API
The Box Collections API manages collections such as Favorites, allowing applications to list available collections and retrieve the items within them for organizing frequently accessed content.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Collections API
description: Needs a description.
paths:
/collections:
get:
operationId: get_collections
summary: Box List all collections
tags:
- Collections
x-box-tag: collections
description: |-
Retrieves all collections for a given user.
Currently, only the `favorites` collection
is supported.
parameters:
- 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: offset
description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
default: 0
- 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 all collections for the given user
content:
application/json:
schema:
$ref: '#/components/schemas/Collections'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/collections/{collection_id}/items:
get:
operationId: get_collections_id_items
summary: Box List collection items
tags:
- Collections
x-box-tag: collections
description: |-
Retrieves the files and/or folders contained within
this collection.
parameters:
- name: collection_id
description: The ID of the collection.
example: '926489'
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
- name: offset
description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
default: 0
- 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 an array of items in the collection.
content:
application/json:
schema:
$ref: '#/components/schemas/Items'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
Collections:
title: Collections
type: object
x-box-resource-id: collections
x-box-tag: collections
description: A list of collections
allOf:
- type: object
description: The part of an API response that describes pagination
properties:
total_count:
description: >-
One greater than the offset of the last entry in the entire
collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
type: integer
format: int64
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
offset:
description: >-
The 0-based offset of the first entry in this set. This will be
the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
type: integer
format: int64
order:
description: >-
The order by which items are returned.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
type: array
items:
type: object
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
type: string
description: The direction to order by, either ascending or descending
example: ASC
enum:
- ASC
- DESC
- properties:
entries:
type: array
description: A list of collections
items:
$ref: '#/components/schemas/Collection'
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
Items:
title: Items
type: object
x-box-resource-id: items
x-box-tag: folders
description: |-
A list of files, folders, and web links in
their mini representation.
allOf:
- type: object
description: The part of an API response that describes pagination
properties:
total_count:
description: >-
One greater than the offset of the last entry in the entire
collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
type: integer
format: int64
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
offset:
description: >-
The 0-based offset of the first entry in this set. This will be
the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
type: integer
format: int64
order:
description: >-
The order by which items are returned.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
type: array
items:
type: object
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
type: string
description: The direction to order by, either ascending or descending
example: ASC
enum:
- ASC
- DESC
- properties:
entries:
description: The items in this collection.
type: array
items:
oneOf:
- $ref: '#/components/schemas/File--Full'
- $ref: '#/components/schemas/Folder--Mini'
- $ref: '#/components/schemas/WebLink'
tags:
- name: Collections