---
title: "Create metadata instance on file"
method: POST
path: "/files/{file_id}/metadata/{scope}/{template_key}"
tags: ["Metadata instances (Files)"]
---

# Create metadata instance on file

`POST /files/{file_id}/metadata/{scope}/{template_key}`

Applies an instance of a metadata template to a file.

In most cases only values that are present in the metadata template
will be accepted, except for the `global.properties` template which accepts
any key-value pair.

## Path parameters

- `file_id` string, required
- `scope` 'global' | 'enterprise', required
- `template_key` string, required

## Request body

- object

## Response `201`

Returns the instance of the template that was applied to the file,
including the data that was applied to the template.

- MetadataFull — The base representation of a metadata instance.
  - `$parent` string — 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}`.
  - `$template` string — The name of the template.
  - `$scope` string — 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.
  - `$version` integer — The version of the metadata instance. This version starts at 0 and increases every time a user-defined property is modified.
  - `$canEdit` boolean — Whether the user can edit this metadata instance.
  - `$id` string, uuid — A UUID to identify the metadata instance.
  - `$type` string — A unique identifier for the "type" of this instance. This is an internal system property and should not be used by a client application.
  - `$typeVersion` integer — 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.

## Other responses

- `400` — Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field.
- `404` — Returns an error when the file or metadata template was not found. * `not_found` - The file could not be found, or the user does not have access to the file. * `instance_tuple_not_found` - The metadata template was not found.
- `409` — Returns an error when an instance of this metadata template is already present on the file. * `tuple_already_exists` - An instance of the metadata template already exists on the file.
- `default` — An unexpected client error.

---

[API](https://skmtc.dev/box/apis/platform-api.md) · [All operations](https://skmtc.dev/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/box/platform-api/revisions/ba8f087e1a4d/schema)