BObox
Metadata instances (Files)

Update metadata instance on file

Changed on

Updates a piece of metadata on a file.

The metadata instance can only be updated if the template has already been applied to the file before. When editing metadata, only values that match the metadata template schema will be accepted.

The update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed.

put/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

op'add' | 'replace' | 'remove' | 'test' | 'move' | 'copy'

The type of change to perform on the template. Some of these are hazardous as they will change existing templates.

pathstring

The location in the metadata JSON object to apply the changes to, in the format of a JSON-Pointer.

The path must always be prefixed with a / to represent the root of the template. The characters ~ and / are reserved characters and must be escaped in the key.

fromstring

The location in the metadata JSON object to move or copy a value from. Required for move or copy operations and must be in the format of a JSON-Pointer.

Example request

[
  {
    "op": "add",
    "path": "/currentState",
    "from": "/nextState"
  }
]

Response

Returns the updated metadata template instance, with the custom template data included.

$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

    • 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