Sample - Box Platform API
PUT/folders/{folder_id}/metadata/{scope}/{template_key}

Update metadata on a folder

Updates an existing metadata instance on a folder with a JSON Patch document. Apply changes only after the metadata template has already been assigned to the folder, and use operations whose values match the template schema. The update is atomic, so no changes are applied if any operation fails.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

3 parameters · 4 body fields
folder_idstringrequired
The unique identifier of the folder whose metadata instance to update.
scopestringrequired
The metadata template scope: global or enterprise.
Allowed:globalenterprise
template_keystringrequired
The name of the metadata template whose instance to update.

A JSON Patch array describing atomic changes to the metadata instance.

opstringoptional
The type of change to perform on the template. Some of these are hazardous as they will change existing templates.
Allowed:addreplaceremovetestmovecopy
pathstringoptional
The location in the metadata JSON object to apply the changes to, in the format of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901). 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.
valuestringoptional
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.
fromstringoptional
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](https://tools.ietf.org/html/rfc6901).

4 status codes
200Returns the updated metadata template instance with its custom template data.
$parentstringoptional
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}`.
$templatestringoptional
The name of the template.
$scopestringoptional
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.
$versionintegeroptional
The version of the metadata instance. This version starts at 0 and increases every time a user-defined property is modified.
$canEditbooleanoptional
Whether the user can edit this metadata instance.
$idstringoptional
A UUID to identify the metadata instance.
$typestringoptional
A unique identifier for the "type" of this instance. This is an internal system property and should not be used by a client application.
$typeVersionintegeroptional
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.
400Returned when the request body is not an array of valid JSON Patch operation objects.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
500Returned in edge cases when the request body is not a valid array of JSON Patch items.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultReturned for an unexpected client error.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 400 is returned when the body is not an array of valid JSON Patch operations. A 500 can be returned when the request body is not a valid array of JSON Patch items. Use a path beginning with /, provide value for add, replace, and test, and provide from for move and copy operations.