Join BoxWorks 2024 to discover what's possible with content and AI!

Update metadata instance on folder

put

https://api.box.com/2.0

/folders/:folder_id/metadata/:scope/:template_key

Updates a piece of metadata on a folder.

The metadata instance can only be updated if the template has already been applied to the folder before. When editing metadata, only values that match the metadata template schema will be accepted.

The update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed.

Related Guides

Metadata Update metadata on an item

Request

authorizationbearer [ACCESS_TOKEN]

content-typeapplication/json-patch+json

Path Parameters

folder_id stringin pathrequired

example12345

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 stringin pathrequired

exampleglobal

The scope of the metadata template

Value is one of global,enterprise

template_key stringin pathrequired

exampleproperties

The name of the metadata template

Request Body

<item> object arrayin bodyrequired

A JSON-Patch specification for the changes to make to the metadata instance.

The changes are represented as a JSON array of operation objects.

[<item>].from stringin bodyoptional

example"/nextState"

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.

[<item>].op stringin bodyoptional

example"add"

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

Value is one of add,replace,remove,test,move,copy

[<item>].path stringin bodyoptional

example"/currentState"

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.

[<item>].value stringin bodyoptional

example"reviewed"

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.

Response

200application/jsonMetadata instance (Full)

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

400application/jsonClient error

Returns an error when the request body is not valid.

bad_request - The request body format is not an array of valid JSON Patch objects.

500application/jsonClient error

Returns an error in some edge cases when the request body is not a valid array of JSON Patch items.

defaultapplication/jsonClient error

An unexpected client error.

put

Update metadata instance on folder

You can now try out some of our APIs live, right here in the documentation.

Request Example

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

TypeScript Gen

await client.folderMetadata.updateFolderMetadataById(
  folder.id,
  'global' as UpdateFolderMetadataByIdScope,
  'properties',
  [
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/abc',
      value: newValue,
    } satisfies UpdateFolderMetadataByIdRequestBody,
  ],
);

Python Gen

client.folder_metadata.update_folder_metadata_by_id(
    folder.id,
    UpdateFolderMetadataByIdScope.GLOBAL.value,
    "properties",
    [
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE.value,
            path="/abc",
            value=new_value,
        )
    ],
)

.NET Gen

await client.FolderMetadata.UpdateFolderMetadataByIdAsync(folderId: folder.Id, scope: UpdateFolderMetadataByIdScope.Global, templateKey: "properties", requestBody: Array.AsReadOnly(new [] {new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/abc", Value = newValue }}));

Swift Gen (Beta)

try await client.folderMetadata.updateFolderMetadataById(folderId: folder.id, scope: UpdateFolderMetadataByIdScope.global, templateKey: "properties", requestBody: [UpdateFolderMetadataByIdRequestBody(op: UpdateFolderMetadataByIdRequestBodyOpField.replace, path: "/abc", value: newValue)])

Java

BoxFolder folder = new BoxFolder(api, "id");
folder.updateMetadata(new Metadata().add("/foo", "bar"));

Python

folder = client.folder(folder_id='22222')
folder_metadata = folder.metadata(scope='enterprise', template='myMetadata')

updates = folder_metadata.start_update()
updates.add('/foo', 'bar')
updates.update('/baz', 'murp', old_value='quux')  # Ensure the old value was "quux" before updating to "murp"

updated_metadata = folder_metadata.update(updates)
print('Updated metadata on folder!')
print(f'foo is now {updated_metadata["foo"]} and baz is now {updated_metadata["baz"]}')

.NET

var updates = new List<BoxMetadataUpdate>()
{
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.test,
        Path = "/competitiveDocument",
        Value = "no"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.remove,
        Path = "/competitiveDocument"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.test,
        Path = "/status",
        Value = "active"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.replace,
        Path = "/competitiveDocument",
        Value = "inactive"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.test,
        Path = "/author",
        Value = "Jones"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.copy,
        From="/author",
        Path = "/editor"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.test,
        Path = "/currentState",
        Value = "proposal"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.move,
        From = "/currentState",
        Path = "/previousState"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.add,
        Path = "/currentState",
        Value = "reviewed"
    }
};
Dictionary<string, object> updatedMetadata = await client.MetadataManager
    .UpdateFolderMetadataAsync("11111", updates, "enterprise", "marketingCollateral");

Node

var updates = [
	{ 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.folders.updateMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", updates)
	.then(metadata => {
		/* metadata -> {
			audience: 'internal',
			documentType: 'Q1 plans',
			status: 'inactive',
			author: 'Jones',
			'$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
			'$parent': 'folder_11111',
			'$id': '2094c584-68e1-475c-a581-534a4609594e',
			'$version': 1,
			'$typeVersion': 0,
			editor: 'Jones',
			previousState: 'proposal',
			currentState: 'reviewed',
			'$template': 'marketingCollateral',
			'$scope': 'enterprise_12345' }
		*/
	});

iOS

client.metadata.update(
    forFolderWithId: "22222",
    scope: "enterprise",
    templateKey: "personnelRecord",
    operations: [
        .test(path: "/department", value: "Sales"),
        .replace(path: "/department", value: "Marketing")
    ]
) { (result: Result<MetadataObject, BoxSDKError>) in
    guard case let .success(metadata) = result {
        print("Error updating metadata")
        return
    }

    print("Employee department updated to \(metadata.keys["department"])")
}

Response Example

{
  "$canEdit": true,
  "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
  "$parent": "folder_59449484661,",
  "$scope": "enterprise_27335",
  "$template": "marketingCollateral",
  "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
  "$typeVersion": 2,
  "$version": 1
}