Skip to main content
PUT
/
folders
/
{folder_id}
/
metadata
/
{scope}
/
{template_key}
cURL
curl -i -X PUT "https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json-patch+json" \
     -d '[
        {
          "op": "test",
          "path": "/competitiveDocument",
          "value": "no"
        },
        {
          "op": "remove",
          "path": "/competitiveDocument"
        },
        {
          "op": "test",
          "path": "/status",
          "value": "active"
        },
        {
          "op": "replace",
          "path": "/status",
          "value": "inactive"
        },
        {
          "op": "test",
          "path": "/author",
          "value": "Jones"
        },
        {
          "op": "copy",
          "from": "/author",
          "path": "/editor"
        },
        {
          "op": "test",
          "path": "/currentState",
          "value": "proposal"
        },
        {
          "op": "move",
          "from": "/currentState",
          "path": "/previousState"
        },
        {
          "op": "add",
          "path": "/currentState",
          "value": "reviewed"
        }
      ]'
{
  "$parent": "folder_59449484661,",
  "$template": "marketingCollateral",
  "$scope": "enterprise_27335",
  "$version": 1,
  "$canEdit": true,
  "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
  "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
  "$typeVersion": 2
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

​
folder_id
string
required

The unique identifier that represent a folder.

The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL https://*.app.box.com/folder/123 the folder_id is 123.

The root folder of a Box account is always represented by the ID 0.

​
scope
enum<string>
required

The scope of the metadata template.

Available options:
global,
enterprise
​
template_key
string
required

The name of the metadata template.

Body

application/json-patch+json
​
op
enum<string>

The type of change to perform on the template. Some of these are hazardous as they will change existing templates.

Available options:
add,
replace,
remove,
test,
move,
copy
Example:

"add"

​
path
string

The location in the metadata JSON object to apply the changes to, in the format of a JSON-Pointer.

The path must always be prefixed with a / to represent the root of the template. The characters ~ and / are reserved characters and must be escaped in the key.

Example:

"/currentState"

​
value

The value to be set or tested.

Required for add, replace, and test operations. For add, if the value exists already the previous value will be overwritten by the new value. For replace, the value must exist before replacing.

For test, the existing value at the path location must match the specified value.

Example:

"reviewed"

​
from
string

The location in the metadata JSON object to move or copy a value from. Required for move or copy operations and must be in the format of a JSON-Pointer.

Example:

"/nextState"

Response

Returns the updated metadata template instance, with the custom template data included.

An instance of a metadata template, which has been applied to a file or folder.

​
$parent
string

The identifier of the item that this metadata instance has been attached to. This combines the type and the id of the parent in the form {type}_{id}.

Example:

"folder_59449484661,"

​
$template
string

The name of the template.

Example:

"marketingCollateral"

​
$scope
string

An ID for the scope in which this template has been applied. This will be enterprise_{enterprise_id} for templates defined for use in this enterprise, and global for general templates that are available to all enterprises using Box.

Example:

"enterprise_27335"

​
$version
integer

The version of the metadata instance. This version starts at 0 and increases every time a user-defined property is modified.

Example:

1

​
$canEdit
boolean

Whether the user can edit this metadata instance.

Example:

true

​
$id
string<uuid>

A UUID to identify the metadata instance.

Maximum string length: 36
Example:

"01234500-12f1-1234-aa12-b1d234cb567e"

​
$type
string

A unique identifier for the "type" of this instance. This is an internal system property and should not be used by a client application.

Example:

"properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0"

​
$typeVersion
integer

The last-known version of the template of the object. This is an internal system property and should not be used by a client application.

Example:

2

​
{key}
any

A value for each of the fields that are present on the metadata template. For the global.properties template this can be a list of zero or more fields, as this template allows for any generic key-value pairs to be stored stored in the template.

Example:

"Aaron Levie"