Update metadata instance on folder

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"
        }
      ]'

client.folder_metadata.update_folder_metadata_by_id(
    folder.id,
    UpdateFolderMetadataByIdScope.ENTERPRISE,
    template_key,
    [
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
            path="/name",
            value="Jack",
        ),
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE, path="/age", value=24
        ),
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
            path="/birthDate",
            value="2000-01-03T02:20:50.520Z",
        ),
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
            path="/countryCode",
            value="CA",
        ),
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
            path="/sports",
            value=["football"],
        ),
    ],
)

await client.folderMetadata.updateFolderMetadataById(
  folder.id,
  'enterprise' as UpdateFolderMetadataByIdScope,
  templateKey,
  [
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/name',
      value: 'Jack',
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/age',
      value: 24,
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/birthDate',
      value: '2000-01-03T02:20:50.520Z',
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/countryCode',
      value: 'CA',
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/sports',
      value: ['football'],
    } satisfies UpdateFolderMetadataByIdRequestBody,
  ],
);

client.getFolderMetadata().updateFolderMetadataById(folder.getId(), UpdateFolderMetadataByIdScope.ENTERPRISE, templateKey, Arrays.asList(new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/name").value("Jack").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/age").value(24L).build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/birthDate").value("2000-01-03T02:20:50.520Z").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/countryCode").value("CA").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/sports").value(Arrays.asList("football")).build()))

await client.FolderMetadata.UpdateFolderMetadataByIdAsync(folderId: folder.Id, scope: UpdateFolderMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/name", Value = "Jack" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/age", Value = 24L },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/birthDate", Value = "2000-01-03T02:20:50.520Z" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/countryCode", Value = "CA" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/sports", Value = Array.AsReadOnly(new [] {"football"}) }}));

{
  "$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
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

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"
        }
      ]'

client.folder_metadata.update_folder_metadata_by_id(
    folder.id,
    UpdateFolderMetadataByIdScope.ENTERPRISE,
    template_key,
    [
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
            path="/name",
            value="Jack",
        ),
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE, path="/age", value=24
        ),
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
            path="/birthDate",
            value="2000-01-03T02:20:50.520Z",
        ),
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
            path="/countryCode",
            value="CA",
        ),
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
            path="/sports",
            value=["football"],
        ),
    ],
)

await client.folderMetadata.updateFolderMetadataById(
  folder.id,
  'enterprise' as UpdateFolderMetadataByIdScope,
  templateKey,
  [
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/name',
      value: 'Jack',
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/age',
      value: 24,
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/birthDate',
      value: '2000-01-03T02:20:50.520Z',
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/countryCode',
      value: 'CA',
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/sports',
      value: ['football'],
    } satisfies UpdateFolderMetadataByIdRequestBody,
  ],
);

client.getFolderMetadata().updateFolderMetadataById(folder.getId(), UpdateFolderMetadataByIdScope.ENTERPRISE, templateKey, Arrays.asList(new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/name").value("Jack").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/age").value(24L).build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/birthDate").value("2000-01-03T02:20:50.520Z").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/countryCode").value("CA").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/sports").value(Arrays.asList("football")).build()))

await client.FolderMetadata.UpdateFolderMetadataByIdAsync(folderId: folder.Id, scope: UpdateFolderMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/name", Value = "Jack" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/age", Value = 24L },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/birthDate", Value = "2000-01-03T02:20:50.520Z" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/countryCode", Value = "CA" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/sports", Value = Array.AsReadOnly(new [] {"football"}) }}));

{
  "$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
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

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

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"

Last modified on January 23, 2026

API reference

API reference

API reference

Update metadata instance on folder

Authorizations

Path Parameters

Body

Response