Create metadata on file

post
https://api.box.com/2.0
/files/:file_id/metadata/:scope/:template_key

Creates a piece of metadata on a file based on the specified template.

Only values that are present in the metadata template will be accepted.

Request

application/json

Path Parameters

stringin pathrequired
12345

The unique identifier that represent a file.

The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the url https://*.app.box.com/files/123 the file_id is 123.

stringin pathrequired
enterprise_27335

The scope of the metadata template

Value is one of "global", "enterprise_<id>"

stringin pathrequired
blueprintTemplate

The name of the metadata template

Response

application/jsonMetadata

Returns an instance of the template that was specified, with the custom template data included.

application/jsonClient Error

If the piece of metadata already exists, a conflict error will be returned. The metadata can then instead be updated with the PUT method.

You can now try out some of our APIs live, right here in the documentation.
Log In

Request Example

cURL
curl -X POST https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "audience: "internal",
       "documentType": "Q1 plans",
       "competitiveDocument": "no",
       "status": "active",
       "author": "Jones",
       "currentState": "proposal"
     }'
.NET
var metadataValues = new Dictionary<string, object>()
{
    { "audience", "internal" },
    { "documentType", "Q1 plans" },
    { "competitiveDocument", "no" },
    { "status", "active" },
    { "author": "M. Jones" },
    { "currentState": "proposal" }
};
Dictionary<string, object> metadata = await client.MetadataManager
    .CreateFileMetadataAsync(fileId: "11111", metadataValues, "enterprise", "marketingCollateral");
Java
// Add property "foo" with value "bar" to the default metadata properties
BoxFile file = new BoxFile(api, "id");
file.createMetadata(new Metadata().add("/foo", "bar"));
Python
metadata = {
    'foo': 'bar',
    'baz': 'quux',
}

applied_metadata = client.file(file_id='11111').metadata().create(metadata)
print('Applied metadata in instance ID {0}'.format(applied_metadata['$id']))
Node
var metadataValues = {
	audience: "internal",
	documentType: "Q1 plans",
	competitiveDocument: "no",
	status: "active",
	author: "Jones",
	currentState: "proposal"
};
client.files.addMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", metadataValues)
	.then(metadata => {
		/* metadata -> {
			audience: 'internal',
			documentType: 'Q1 plans',
			competitiveDocument: 'no',
			status: 'active',
			author: 'Jones',
			currentState: 'proposal',
			'$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
			'$parent': 'file_11111',
			'$id': '2094c584-68e1-475c-a581-534a4609594e',
			'$version': 0,
			'$typeVersion': 0,
			'$template': 'marketingCollateral',
			'$scope': 'enterprise_12345' }
		*/
	});

Response Example

{
  "$canEdit": true,
  "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
  "$parent": "folder_59449484661,",
  "$scope": "enterprise_27335",
  "$template": "blueprintTemplate",
  "$type": "blueprintTemplate-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
  "$typeVersion": 2,
  "$version": 1
}