BObox
Metadata instances (Files)

Create metadata instance on file

Changed on

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.

post/files/{file_id}/metadata/{scope}/{template_key}

Request

  • Base URL
    https://api.box.com/2.0
  • URL
    https://api.box.com/2.0/files/{file_id}/metadata/{scope}/{template_key}
  • Auth
    OAuth 2
    Authorization code: https://account.box.com/api/oauth2/authorize
    Token URL: https://api.box.com/oauth2/token

Path parameters

file_idstring required

The unique identifier that represents 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.

scope'global' | 'enterprise' required

The scope of the metadata template.

template_keystring required

The name of the metadata template.

Request body

object required

Example request

{
  "name": "Aaron Levie"
}

Response

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

$parentstring

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}.

$templatestring

The name of the template.

$scopestring

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.

$versioninteger

The version of the metadata instance. This version starts at 0 and increases every time a user-defined property is modified.

$canEditboolean

Whether the user can edit this metadata instance.

$idstring uuid

A UUID to identify the metadata instance.

$typestring

A unique identifier for the "type" of this instance. This is an internal system property and should not be used by a client application.

$typeVersioninteger

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.

Example response

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

Changes

  • c4d5303fa5c3Revision changes
    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • info

      added subschema #2 subschema #3 to the response body allOf list for the response status

    • info

      removed subschema #2 subschema #3 from the response body allOf list for the response status