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

Create a metadata instance on a file

Creates and applies a metadata template instance to a specific file. Use scope and template_key to identify the template, then provide values for fields defined by that template; the global.properties template also accepts arbitrary key-value pairs. A file can have only one instance of a given metadata template.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

3 parameters
file_idstringrequired
The unique identifier of the file to which you want to apply the metadata template.
scopestringrequired
The metadata template scope. Must be `global` or `enterprise`.
Allowed:globalenterprise
template_keystringrequired
The name of the metadata template to apply to the file.

5 status codes
201Returns the newly applied metadata template instance, including the metadata values and instance details.
$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 a body value does not match the metadata template schema, references a field that does not exist, or uses an invalid value or type.
codestringoptional
A Box-specific error code.
messagestringoptional
A short message describing the error.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
404Returned when the file or metadata template cannot be found, or the authenticated user does not have access to the file.
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.
409Returned when an instance of the selected metadata template already exists on the file.
codestringoptional
A Box-specific error code.
messagestringoptional
A short message describing the error.
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 a body value does not match the metadata template, references an unknown field, or uses an invalid field option or type. A 404 is returned when file_id or the metadata template identified by scope and template_key cannot be found. A 409 is returned when an instance of the specified template already exists on the file.