Sample - Box Platform API
PUT/files/{file_id}/metadata/{scope}/{template_key}

Update metadata on a file

Updates an existing metadata instance on a file. Supply JSON Patch operations that match the metadata template schema; the update is applied atomically, so invalid operations leave the instance unchanged.

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

An optional JSON Patch document containing an array of operations to apply to the existing 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 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.
defaultAn 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 request body is not an array of valid JSON Patch objects. op must be one of add, replace, remove, test, move, or copy, and path must use a JSON Pointer beginning with /. A 500 is returned in edge cases when the request body is not a valid array of JSON Patch items.