Metadata API Documentation

Contents

Metadata is a newer API feature, so please expect more frequent updates and improvements to the APIs. If you have any questions, please contact us at metadata@box.com.

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 "clientNumber":"820183" and "clientName":"bioMedicalCorp".

Metadata can be used for many purposes. Enterprises 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. Metadata is also visible in the Box Web Application. To learn more, please visit the help documentation.

The Basics: Metadata Templates

Metadata templates are currently set up through the Box team. Please email metadata@box.com for access. We will also provide programmatic template information if requested.

Metadata that belongs to a file is grouped by templates. Templates 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 marketingCollateral template may define where and when specific marketing content should be used. You can also see the representation of the template instance in the Box web application while navigating to a file preview:

Metadata Preview

Templates belong to and are defined uniquely by each enterprise. Currently, there are four attributes supported by templates:

Understanding Template Instances

Metadata that belongs to a file is grouped by template instances. Each file can have multiple distinct template instances associated with it, such as a marketingCollateral and retentionPolicy template instances. Template instances are also grouped by scopes. Currently, the only scopes support are enterprise and global. Enterprise scopes are defined on a per enterprises basis, whereas global scopes are Box application-wide. Attribute order within template instances is not guaranteed.

Attributes of a template instance
$id
string
36 character UUID to identify the metadata object
$type
string
Defines the metadata template. The format is “template_name-UUID”
$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 the template. These values also have a corresponding display name that are viewable in applications like the Box web application. The total char limit for a template 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 marketingCollateral Template Instance

{
"$type": "marketingCollateral-1199c73f-11aa-439a-a7d0-e981fc6cc22f",
"$parent": "file_6122548033",
"$id": "5995c847-7efe-483c-bf27-1b0dba2a9471",
"audience": "external",
"vertical": "healthcare",
"documentType": "datasheet",
"status": "active"
}

Creating Metadata

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

Method

POST /files/{file_id}/metadata/{scope}/{template} 

URL Parameters

Headers

Content-Type Must be application/json
Type: string

Request Body Attributes

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

Returns

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

Example Request for the marketingCollateral template

curl https://api.box.com/2.0/files/6122548033/metadata/enterprise/marketingCollateral \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"audience":"external", "vertical": "healthcare", "documentType": "datasheet", "status": "active"}' \
-X POST

Example Response

{
"audience": "external",
"vertical": "healthcare",
"documentType": "datasheet",
"status": "active",
"$type": "marketingCollateral-1199c73f-11aa-439a-a7d0-e981fc6cc22f",
"$parent": "file_6122548033",
"$id": "fab04c3b-bf72-4726-80d1-d87f8cb87592"
}

Retrieving Metadata

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

Method

GET /files/{file_id}/metadata/{scope}/{template} 

URL Parameters

None are accepted

Returns

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

Example Request for the marketingCollateral template

curl https://api.box.com/2.0/files/6122548033/metadata/enterprise/marketingCollateral \
-H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
"audience": "external",
"vertical": "healthcare",
"documentType": "datasheet",
"status": "active",
"$type": "marketingCollateral-1199c73f-11aa-439a-a7d0-e981fc6cc22f",
"$parent": "file_6122548033",
"$id": "1e3ab159-3737-405e-9d9e-de3cebdd5e29"
}

Updating Metadata

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

Method

 PUT /files/{file_id}/metadata/{scope}/{template}
Template 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 template that includes key:value pairs defined by a user or application. If there is no template instance present, a 404 HTTP status code of not_found will be returned

Example marketingCollateral Template Instance Before An Update

{
"$type": "marketingCollateral-1199c73f-11aa-439a-a7d0-e981fc6cc22f",
"$parent": "file_6122548033",
"$id": "d55c2a68-6032-447a-a5fd-2539c29db5fc",
"audience": "external",
"documentType": "presentation",
"status": "active"
}

Example Update Request for the marketingCollateral Template Instance

curl https://api.box.com/2.0/files/6122548033/metadata/enterprise/marketingCollateral \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json-patch+json" \
-d '[{"op": "test", "path":"/audience", "value":"external"}, { "op": "replace", "path":"/audience", "value": "internal"}, {"op": "test", "path":"/status", "value":"active"}, { "op": "remove", "path":"/status"}, { "op": "add", "path":"/competitiveDocument", "value": "yes"}]' \
-X PUT

Response

{
"$type": "marketingCollateral-1199c73f-11aa-439a-a7d0-e981fc6cc22f",
"$parent": "file_6122548033",
"$id": "d55c2a68-6032-447a-a5fd-2539c29db5fc",
"audience": "internal",
"documentType": "presentation",
"competitiveDocument": "yes"
}

Deleting Metadata

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

Method

 DELETE /files/{file_id}/metadata/{scope}/{template} 

URL Parameters

None are accepted

Returns

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

Example Request for the marketingCollateral template

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

Response

204 response

Global Properties Template

Every file on Box has access to the global properties template. The Properties template is a bucket of free form key:value pairs, with no schema associated with it. Properties are ideal for scenarios where applications want to write metadata to file objects in a flexible way, without pre-defined template structure.

Properties follow all the conventions of standard templates, except for being located at a different endpoint. All requests made to the properties template must be made to /files/{file_id}/metadata/global/properties.

The previous endpoint of /files/{file_id}/metadata/properties will still be supported.

Properties can also be viewed within the web application under “Additional Attributes”:

Screen Shot 2015-02-10 at 2.23.00 PM

Searching for files with metadata

Metadata is indexed by the Box search engine and is available through the search endpoint. Metadata is indexed for both relevance ranking and advanced search through templates. Please note that the Box search engine takes about 5-10 mins between data entry and being available in the search index.

Metadata influencing search relevance

Metadata values are treated like any other file information when it comes to the search index. If you are searching for a term “datasheet” via the search endpoint, you may receive file objects returned that have the term “datasheet” listed in the file name, file body, or metadata values. To learn more about how to search within Box, please refer to the following search tutorial.

Advanced search through templates

The search endpoint has the ability to handle searching through templates. To do so, you would append the mdfilters parameter into your search query. This entirety of the mdfilters parameter must be written in JSON and be URL encoded when submitting your search request. The following are the parameters of the mdfilters parameter:

templateKey
string
The key name of the template you want to search for. Currently, only searching for one template at a time is supported.
scope
string
The scope of the template. Currently, only enterprise and global are supported
filters
string
Keys and values of the template you want to search within. For floats and dates, you can include an upper bound parameter lt or lower bound parameter gt or both bounds. An example JSON parameter of a “contractExpiration” before 08-01-16 would be listed as {"contractExpiration":{"lt":"2016-08-01T00:00-00:00"}}

Example advanced search request with the marketingCollateral template

Request before URL encoding


https://api.box.com/2.0/search?mdfilters=[{"templateKey":"marketingCollateral", "scope":"enterprise", "filters":{"documentType": "datasheet"}}]

Request after URL encoding


curl https://api.box.com/2.0/search?mdfilters=%5B%7B%22templateKey%22%3A%22marketingCollateral%22%2C%20%22scope%22%3A%22enterprise%22%2C%20%22filters%22%3A%7B%22documentType%22%3A%20%22datasheet%22%7D%7D%5D \
-H "Authorization: Bearer ACCESS_TOKEN" 

Example Response


{
    "total_count": 2,
    "entries": [
        {
            "type": "file",
            "id": "27201036412",
            "sequence_id": "0",
            "etag": "0",
            "sha1": "71402e9009892ceb7210558abbe720a8e068bd8a",
            "name": "boxdev.png",
            "description": "",
            "size": 6708,
            "path_collection": {
                "total_count": 2,
                "entries": [
                    {
                        "type": "folder",
                        "id": "0",
                        "sequence_id": null,
                        "etag": null,
                        "name": "All Files"
                    },
                    {
                        "type": "folder",
                        "id": "575496314",
                        "sequence_id": "3",
                        "etag": "3",
                        "name": "Marketing Materials"
                    }
                ]
            },
            "created_at": "2015-03-08T20:34:51-07:00",
            "modified_at": "2015-03-08T20:34:51-07:00",
            "trashed_at": null,
            "purged_at": null,
            "content_created_at": "2015-03-08T14:41:58-07:00",
            "content_modified_at": "2015-03-08T14:41:58-07:00",
            "created_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "modified_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "owned_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "shared_link": null,
            "parent": {
                "type": "folder",
                "id": "575496314",
                "sequence_id": "3",
                "etag": "3",
                "name": "Marketing Materials"
            },
            "item_status": "active"
        },
        {
            "type": "file",
            "id": "26776387434",
            "sequence_id": "3",
            "etag": "3",
            "sha1": "72d773345dbba9cfb012c4a889a4fc6840e59bfa",
            "name": "2014 Companies.xlsx",
            "description": "",
            "size": 91821,
            "path_collection": {
                "total_count": 3,
                "entries": [
                    {
                        "type": "folder",
                        "id": "0",
                        "sequence_id": null,
                        "etag": null,
                        "name": "All Files"
                    },
                    {
                        "type": "folder",
                        "id": "575496314",
                        "sequence_id": "3",
                        "etag": "3",
                        "name": "Marketing Materials"
                    },
                    {
                        "type": "folder",
                        "id": "606618154",
                        "sequence_id": "0",
                        "etag": "0",
                        "name": "West"
                    }
                ]
            },
            "created_at": "2015-02-26T22:20:44-08:00",
            "modified_at": "2015-02-26T22:23:15-08:00",
            "trashed_at": null,
            "purged_at": null,
            "content_created_at": "2015-02-06T16:38:26-08:00",
            "content_modified_at": "2015-02-06T16:38:26-08:00",
            "created_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "modified_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "owned_by": {
                "type": "user",
                "id": "10523870",
                "name": "Ted Blosser",
                "login": "ted+demo@box.com"
            },
            "shared_link": null,
            "parent": {
                "type": "folder",
                "id": "606618154",
                "sequence_id": "0",
                "etag": "0",
                "name": "West"
            },
            "item_status": "active"
        }
    ],
    "limit": 30,
    "offset": 0
}

SDKs

Metadata is currently available in the following SDKs:

Frequently Asked Questions

 

Who can get access to metadata?

Metadata will be available on accounts under the Enterprise and Enterprise Elite plans. It is also available for developer accounts for testing purposes.

Where can I send feedback or feature requests to?

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

How can I learn more about the metadata roadmap?

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

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.