Metadata API Documentation

Disclaimer: Metadata is in beta and is subject to frequent breaking and additive changes. By using the beta, you are acknowledging that you have read and agreed to our beta terms of service

Contents

Overview

At its core, metadata allows users and applications to define and store custom data associated with their files. Metadata consists of key:value pairs that belong to files. For example, an important contract may have key:value pairs of "client_number":"820183" and "client_name":"Biomedical Corp".

Metadata can be used for many purposes. Customers may want to have a better way to organize their digital assets for their marketing teams or developers may want to provide advanced content functionality such as facilitating workflows or approvals.

As metadata evolves, we will be incrementally releasing value added features and functionality. These features will utilize the database-like behavior metadata affords, such as the ability to hone searches in on specific fields, or enforcing strict schema on values that are added.

As a reminder, metadata is currently in beta and you should expect changes to occur. Because of our rapid iteration, we recommend that you check back with this documentation frequently.

The Basics: Metadata Types

Metadata that belongs to a file is grouped by types. Types allow the metadata service to provide a multitude of services, such as pre-defining sets of key:value pairs or schema enforcement on specific fields. For example, a retention_policy type may define how long a file should be retained for. Or, a contract_details type would provide common information about a contract such as the name of the customer or the date the contract expires.

We currently only expose one default type properties which enforces a string schema for its key:value pairs. In the future, you can expect that more types will be introduced, in addition to custom defined types.

metadata_types

Understanding Type Instances

Metadata that belongs to a file is grouped by type instances. Each file can have multiple distinct type instances associated with it, such as a properties and retention_policy type instances.

Attributes of a type instance
$id
string
36 character UUID to identify the metadata object
$type
string
Defines the metadata type. Currently, only the properties type exists, but there will be additional types in the future
$parent
string
The object ID the metadata object belongs to. Currently, only support the file object is supported. To learn more about the file object, please review the documentation. Updating metadata does not directly affect the parent object, such as changing the modified_at field for a file.
custom-defined-key(s)
max of 128 keys

Custom value(s) defined by a user or application. For the properties type, there is a max of 256 char for keys and 4096 char for values. The total char limit for a type instance can not exceed 16384 char. Since the $ char is reserved for metadata service keys, custom values can not be prefixed with the $ char.

Example Metadata properties Type Instance

{
    "$id":"b1372a20-a33a-11e3-a5e2-0800200c9a66",
    "$type": "properties",
    "$parent": "file_14208358187",
    "customer": "P&G",
    "contact": "Lafley, Alan"
}

Creating Metadata

Used to create the metadata type instance for a corresponding Box file.

Method

POST /files/{file_id}/metadata/{type} 

URL Parameters

Headers

Content-Type Must be application/json
Type: string

Request Body Atrtributes

custom-defined-key(s)
required
Custom value(s) defined by a user or application
Type: string

Returns

An instance of the type that includes key:value pairs defined by a user or application. If the properties instance already exists, a 409 HTTP status code of conflict will be returned and the update method should be used.

Example Request for the properties type

curl https://api.box.com/2.0/files/552345101/metadata/properties \
-H "Authorization: Bearer ACCESS_TOKEN"
-H "Content-Type: application/json" \
-d '{"client_number":"820183", "client_name": "Biomedical Corp", "case_reference": "A83JAA", "case_type": "Employment Litigation", "assigned_attorney": "Francis Burke" , "case_status": "in-progress"}' \
-X POST

Example Response

{
    "$id":"c79896a0-a33f-11e3-a5e2-0800200c9a66",
    "$type": "properties",
    "$parent": "file_552345101",
    "client_number": "820183",
    "client_name": "Biomedical Corp",
    "case_reference": "A83JAA",
    "case_type": "Employment Litigation",
    "assigned_attorney": "Francis Burke",
    "case_status": "in-progress"
}

Retrieving Metadata

Used to retrieve the metadata type instance for a corresponding Box file.

Method

GET /files/{file_id}/metadata/{type} 

URL Parameters

None are accepted

Returns

An instance of the type that includes key:value pairs defined by a user or application. If there is no type instance present, a 404 HTTP status code of not_found will be returned.

Example Request for the properties type

curl https://api.box.com/2.0/files/552345101/metadata/properties \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
    "$id":"c79896a0-a33f-11e3-a5e2-0800200c9a66",
    "$type": "properties",
    "$parent": "file_552345101",
    "client_number": "820183",
    "client_name": "Biomedical Corp",
    "case_reference": "A83JAA",
    "case_type": "Employment Litigation",
    "assigned_attorney": "Francis Burke",
    "case_status": "in-progress"
}

Updating Metadata

Used to update the type instance. Updates can be either add, replace, remove , or test. The type instance can only be updated if the type instance already exists.

Method

 PUT /files/{file_id}/metadata/{type}
Type instances are updated using JSON patch operations specified by RFC 6902. For PUT requests, the application/json-patch+json header is required.

Patch operations will be processed sequentially. For example, you can run a test operation before an replace operation to ensure the correct value is being updated. If the value is incorrect, you will receive a HTTP response of 409 conflict. Multiple JSON patch operations can be sent with each request, up to 128. However, if there is a failure in any operation, the entire patch will fail.

To use reserved characters like “/” and “~” defined by RFC 6902, please refer to section 4. It demonstrates escaping “/” as “~1″ and “~” as “~0″.

Headers

Content-Type Must be application/json-patch+json
Type: string

Request Body Attributes for JSON patch operation

op
required
The operation type. Must be add, replace, remove, or test
Type: string
path
required
The path that designates the key. Must be prefixed with a /
Type: string
value
required for add and replace operations

The value to be set. If value already exists, then previous value will be overwritten by the new value
Type: string

Returns

An instance of the type that includes key:value pairs defined by a user or application. If there is no type instance present, a 404 HTTP status code of not_found will be returned

Example properties Type Instance Before An Update

{
    "$id":"c79896a0-a33f-11e3-a5e2-0800200c9a66",
    "$type": "properties",
    "$parent": "file_552345101",
    "client_number": "820183",
    "client_name": "Biomedical Corp",
    "case_reference": "A83JAA",
    "case_type": "Employment Litigation",
    "assigned_attorney": "Francis Burke",
    "case_status": "in-progress"
}

Example Update Request for the properties Type Instance

curl https://api.box.com/2.0/files/FILE_ID/metadata/properties \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json-patch+json" \
-d '[{"op": "test", "path":"/assigned_attorney", "value":"Francis Burke"}, { "op": "replace", "path":"/assigned_attorney", "value": "Eugene Huang"}, {"op": "test", "path":"/case_status", "value":"in-progress"}, { "op": "remove", "path":"/case_status"}, { "op": "add", "path":"/retention_length", "value": "7_years"}]' \
-X PUT

Response

{
    "$id":"c79896a0-a33f-11e3-a5e2-0800200c9a66",
    "$type": "properties",
    "$parent": "file_552345101",
    "client_number": "820183",
    "client_name": "Biomedical Corp",
    "case_reference": "A83JAA",
    "case_type": "Employment Litigation",
    "assigned_attorney": "Eugene Huang",
    "retention_length": "7_years"
}

Deleting Metadata

Used to delete the type instance. To delete custom key:value pairs within a type instance, you should refer to the updating metadata section.

Method

 DELETE /files/{file_id}/metadata/{type} 

URL Parameters

None are accepted

Returns

An empty HTTP 204 response to confirm the deletion of the type instance.

Example Request for the properties type

curl https://api.box.com/2.0/files/FILE_ID/metadata/properties \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE

Response

Integration with Box Search

Values within metadata type instances are indexed by the Box search engine. For example, if there is key:value pair of "client_number":"820183" in the properties type instance, the value 820183 will be indexed by Box. Therefore, if you perform a keyword search for 820183, you could assume that there will be relevant results pertaining to your file.

To perform a search, please refer to the documentation. Currently, metadata only influences the relevance of your search query.

SDKs

We’ve integrated metadata into our mobile SDKs. They can be found here:

Frequently Asked Questions

How do you get access to metadata?

To get access to the beta, please email metadata-beta@box.com with the email address associated with your Box account.

Who can get access to metadata?

Metadata will be available to all users and developers via the API. Access to metadata features within other Box applications like the Box Web Application may be reserved for Enterprise and Enterprise Plus plans.

How long does it take to become activated?

We activate metadata in batches by the end of each working week. If you send us a list of users to activate, each user will receive a confirmation email.

Where can I send feedback or feature requests to?

Feedback and feature requests should be sent to metadata-beta@box.com.

How can I learn more about the metadata roadmap?

The metadata roadmap is confidential, but if you email metadata-beta@box.com, we are happy to engage in a dialog with you.

When will metadata go into GA?

We are committed to building a great product, so we will be iterating and improving the service as we receive feedback from customers. After we are confident that the product is feature complete and we can meet our enterprise-grade SLAs, we will declare the service GA.

Is metadata part of the Content API? If so, what are the differences between the two?

Metadata is part of the Content API and adheres to most of its standards. The primary difference is that metadata is the only resource that leverages the JSON patch RFC for updates. Additionally, metadata does not support fields or If-Match headers.