Sample - Box Platform API
PUT/metadata_templates/{scope}/{template_key}/schema

Update a metadata template

Updates an existing metadata template by applying a JSON Patch-style array of operations. Use scope and template_key to identify the template, and provide the appropriate operation fields for changes such as adding, editing, reordering, or removing fields and options. The update is applied atomically.

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

2 parameters · 8 body fields
scopestringrequired
The scope containing the metadata template. Must be `global` or `enterprise`.
Allowed:globalenterprise
template_keystringrequired
The name of the metadata template to update.

A JSON Patch-style array of metadata template update operations, applied atomically.

opstringrequired
The type of change to perform on the template. Some of these are hazardous as they will change existing templates.
Allowed:editTemplateaddFieldreorderFieldsaddEnumOptionreorderEnumOptionsreorderMultiSelectOptionsaddMultiSelectOptioneditFieldremoveFieldeditEnumOptionremoveEnumOptioneditMultiSelectOption
dataobjectoptional
The data for the operation. This will vary depending on the operation being performed.
fieldKeystringoptional
For operations that affect a single field this defines the key of the field that is affected.
fieldKeysarray<string>optional
For operations that affect multiple fields this defines the keys of the fields that are affected.
enumOptionKeystringoptional
For operations that affect a single `enum` option this defines the key of the option that is affected.
enumOptionKeysarray<string>optional
For operations that affect multiple `enum` options this defines the keys of the options that are affected.
multiSelectOptionKeystringoptional
For operations that affect a single multi select option this defines the key of the option that is affected.
multiSelectOptionKeysarray<string>optional
For operations that affect multiple multi select options this defines the keys of the options that are affected.

5 status codes
200Returns the updated metadata template with its custom template data.
idstringrequired
The ID of the metadata template.
typestringrequired
The value will always be `metadata_template`.
Allowed:metadata_template
scopestringoptional
The scope of the metadata template can either be `global` or `enterprise_*`. The `global` scope is used for templates that are available to any Box enterprise. The `enterprise_*` scope represents templates that have been created within a specific enterprise, where `*` will be the ID of that enterprise.
templateKeystringoptional
A unique identifier for the template. This identifier is unique across the `scope` of the enterprise to which the metadata template is being applied, yet is not necessarily unique across different enterprises.
displayNamestringoptional
The display name of the template. This can be seen in the Box web app and mobile apps.
hiddenbooleanoptional
Defines if this template is visible in the Box web app UI, or if it is purely intended for usage through the API.
fieldsarray<object>optional
An ordered list of template fields which are part of the template. Each field can be a regular text field, date field, number field, as well as a single or multi-select list.
copyInstanceOnItemCopybooleanoptional
Whether or not to include the metadata when a file or folder is copied.
400Returned when the request body does not contain a valid metadata schema.
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.
403Returned when the request body specifies a scope that the authenticated user is not allowed to use for template operations.
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.
404Returned when the requested metadata template does not exist.
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 a valid metadata schema or an operation is invalid. scope must be global or enterprise, and each operation must include an op value from the supported metadata template operations. A 403 is returned when the authenticated user is not allowed to use the requested scope, and a 404 is returned when the template does not exist.