The Box Metadata Templates API allows creation and management of metadata templates that define the structure and fields of metadata that can be applied to files and folders in Box for custom categorization and organization.
openapi: 3.1.0
info:
title: Box Metadata Templates API
description: Needs a description.
paths:
/metadata_templates:
get:
operationId: get_metadata_templates
summary: Box Find metadata template by instance ID
tags:
- Metadata Templates
x-box-tag: metadata_templates
x-box-sanitized: true
description: |-
Finds a metadata template by searching for the ID of an instance of the
template.
parameters:
- name: metadata_instance_id
description: The ID of an instance of the metadata template to find.
example: 01234500-12f1-1234-aa12-b1d234cb567e
in: query
required: true
schema:
type: string
format: uuid
responses:
'200':
description: |-
Returns a list containing the 1 metadata template that matches the
instance ID.
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataTemplates'
'400':
description: Returned when the request parameters are not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema:
get:
operationId: >-
get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema
summary: Box List all classifications
tags:
- Metadata Templates
x-box-tag: classifications
x-box-sanitized: true
description: >-
Retrieves the classification metadata template and lists all the
classifications available to this enterprise.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.
responses:
'200':
description: >-
Returns the `securityClassification` metadata template, which
contains
a `Box__Security__Classification__Key` field that lists all the
classifications available to this enterprise.
content:
application/json:
schema:
$ref: '#/components/schemas/ClassificationTemplate'
'400':
description: Returned if any of the request parameters are not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returned when a template name is not correct. Please make sure
the URL for the request is correct.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#add:
put:
operationId: >-
put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#add
summary: Box Add classification
tags:
- Metadata Templates
x-box-tag: classifications
description: >-
Adds one or more new classifications to the list of classifications
available to the enterprise.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.
requestBody:
content:
application/json:
schema:
required:
- items
description: |-
An array that contains one or more classifications to add to
the enterprise's list of classifications.
type: array
items:
type: object
description: A single classification to add to the enterprise.
required:
- op
- fieldKey
- data
properties:
op:
type: string
example: addEnumOption
description: |-
The type of change to perform on the classification
object.
enum:
- addEnumOption
fieldKey:
type: string
example: Box__Security__Classification__Key
description: |-
Defines classifications
available in the enterprise.
enum:
- Box__Security__Classification__Key
data:
type: object
required:
- key
description: The details of the classification to add.
properties:
key:
type: string
example: Sensitive
description: >-
The label of the classification as shown in the web
and
mobile interfaces. This is the only field required to
add a classification.
staticConfig:
type: object
description: A static configuration for the classification.
properties:
classification:
type: object
description: Additional details for the classification.
properties:
classificationDefinition:
type: string
example: Sensitive information that must not be shared.
description: A longer description of the classification.
colorID:
type: integer
format: int64
example: 4
description: >-
An internal Box identifier used to assign a
color to
a classification label.
Mapping between a `colorID` and a color may
change
without notice. Currently, the color mappings
are as
follows.
* `0`: Yellow
* `1`: Orange
* `2`: Watermelon red
* `3`: Purple rain
* `4`: Light blue
* `5`: Dark blue
* `6`: Light green
* `7`: Gray
responses:
'200':
description: >-
Returns the updated `securityClassification` metadata template,
which
contains a `Box__Security__Classification__Key` field that lists all
the classifications available to this enterprise.
content:
application/json:
schema:
$ref: '#/components/schemas/ClassificationTemplate'
'400':
description: Returned if any of the request parameters are not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returned when a template name is not correct. Please make sure
the URL for the request is correct.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#update:
put:
operationId: >-
put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#update
summary: Box Update classification
tags:
- Metadata Templates
x-box-tag: classifications
x-box-sanitized: true
description: >-
Updates the labels and descriptions of one or more classifications
available to the enterprise.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.
requestBody:
content:
application/json-patch+json:
schema:
description: An array that contains one or more classifications to update.
type: array
required:
- items
items:
type: object
description: A single classification to update.
required:
- op
- fieldKey
- enumOptionKey
- data
properties:
op:
type: string
example: editEnumOption
description: |-
The type of change to perform on the classification
object.
enum:
- editEnumOption
fieldKey:
type: string
example: Box__Security__Classification__Key
description: |-
Defines classifications
available in the enterprise.
enum:
- Box__Security__Classification__Key
enumOptionKey:
type: string
example: Sensitive
description: The original label of the classification to change.
data:
type: object
required:
- key
description: The details of the updated classification.
properties:
key:
type: string
example: Very Sensitive
description: |-
A new label for the classification, as it will be
shown in the web and mobile interfaces.
staticConfig:
type: object
description: A static configuration for the classification.
properties:
classification:
type: object
description: Additional details for the classification.
properties:
classificationDefinition:
type: string
example: Sensitive information that must not be shared.
description: A longer description of the classification.
colorID:
type: integer
format: int64
example: 4
description: >-
An internal Box identifier used to assign a
color to
a classification label.
Mapping between a `colorID` and a color may
change
without notice. Currently, the color mappings
are as
follows.
* `0`: Yellow
* `1`: Orange
* `2`: Watermelon red
* `3`: Purple rain
* `4`: Light blue
* `5`: Dark blue
* `6`: Light green
* `7`: Gray
responses:
'200':
description: >-
Returns the updated `securityClassification` metadata template,
which
contains a `Box__Security__Classification__Key` field that lists all
the classifications available to this enterprise.
content:
application/json:
schema:
$ref: '#/components/schemas/ClassificationTemplate'
'400':
description: Returned if any of the request parameters are not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returned when a template name is not correct. Please make sure
the URL for the request is correct.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/metadata_templates/{scope}/{template_key}/schema:
get:
operationId: get_metadata_templates_id_id_schema
summary: Box Get metadata template by name
tags:
- Metadata Templates
x-box-tag: metadata_templates
x-box-sanitized: true
description: >-
Retrieves a metadata template by its `scope` and `templateKey` values.
To find the `scope` and `templateKey` for a template, list all templates
for
an enterprise or globally, or list all templates applied to a file or
folder.
parameters:
- name: scope
description: The scope of the metadata template
example: global
in: path
required: true
schema:
type: string
enum:
- global
- enterprise
- name: template_key
description: The name of the metadata template
example: properties
in: path
required: true
schema:
type: string
responses:
'200':
description: |-
Returns the metadata template matching the `scope`
and `template` name.
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataTemplate'
'400':
description: >-
Returned if any of the request parameters are not valid.
* `bad_request`: Often returned when the scope of the template is
not
recognised. Please make sure to use either `enterprise` or `global` as
the `scope` value.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: >-
Returned when a template with the given `scope` and `template_key`
can not
be found.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
put:
operationId: put_metadata_templates_id_id_schema
tags:
- Metadata Templates
x-box-tag: metadata_templates
x-box-sanitized: true
summary: Box Update metadata template
description: >-
Updates a metadata template.
The metadata template can only be updated if the template
already exists.
The update is applied atomically. If any errors occur during the
application of the operations, the metadata template will not be
changed.
parameters:
- name: scope
description: The scope of the metadata template
example: global
in: path
required: true
schema:
type: string
enum:
- global
- enterprise
- name: template_key
description: The name of the metadata template
example: properties
in: path
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
description: |-
A [JSON-Patch](https://tools.ietf.org/html/rfc6902)
specification for the changes to make to the metadata
template.
The changes are represented as a JSON array of
operation objects.
type: array
items:
title: A metadata template update operation
description: >-
A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation
for a
change to make to the metadata instance.
type: object
required:
- op
properties:
op:
type: string
example: addEnumOption
enum:
- editTemplate
- addField
- reorderFields
- addEnumOption
- reorderEnumOptions
- reorderMultiSelectOptions
- addMultiSelectOption
- editField
- removeField
- editEnumOption
- removeEnumOption
- editMultiSelectOption
- removeMultiSelectOption
description: >-
The type of change to perform on the template. Some
of these are hazardous as they will change existing
templates.
data:
type: object
description: >-
The data for the operation. This will vary depending on
the
operation being performed.
example:
name: Aaron Levie
additionalProperties:
allOf:
- {}
- example: Aaron Levie
- description: >-
A value for each of the fields that are present
on the metadata template.
For the `global.properties` template this can be
a list of zero or more fields,
as this template allows for any generic key-value
pairs
to be stored stored in the template.
x-box-example-key: name
fieldKey:
type: string
example: category
description: >-
For operations that affect a single field this defines the
key of
the field that is affected.
fieldKeys:
type: array
items:
type: string
example:
- category
- name
description: >-
For operations that affect multiple fields this defines
the keys
of the fields that are affected.
enumOptionKey:
description: >-
For operations that affect a single `enum` option this
defines
the key of the option that is affected.
type: string
example: option1
enumOptionKeys:
description: >-
For operations that affect multiple `enum` options this
defines
the keys of the options that are affected.
type: array
items:
type: string
example:
- option1
- option2
- option3
multiSelectOptionKey:
description: >-
For operations that affect a single multi select option
this
defines the key of the option that is affected.
type: string
example: option1
multiSelectOptionKeys:
description: >-
For operations that affect multiple multi select options
this
defines the keys of the options that are affected.
type: array
items:
type: string
example:
- option1
- option2
- option3
responses:
'200':
description: |-
Returns the updated metadata template, with the
custom template data included.
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataTemplate'
'400':
description: The request body does not contain a valid metadata schema.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: |-
The request body contains a scope that the user is not
allowed to create templates for.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: The requested template could not be found
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
delete:
operationId: delete_metadata_templates_id_id_schema
summary: Box Remove metadata template
tags:
- Metadata Templates
x-box-tag: metadata_templates
x-box-sanitized: true
description: |-
Delete a metadata template and its instances.
This deletion is permanent and can not be reversed.
parameters:
- name: scope
description: The scope of the metadata template
example: global
in: path
required: true
schema:
type: string
enum:
- global
- enterprise
- name: template_key
description: The name of the metadata template
example: properties
in: path
required: true
schema:
type: string
responses:
'204':
description: |-
Returns an empty response when the metadata
template is successfully deleted.
'400':
description: Request body does not contain a valid metadata schema.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: |-
Request body contains a scope that the user is not allowed to
create a template for.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/metadata_templates/{template_id}:
get:
operationId: get_metadata_templates_id
summary: Box Get metadata template by ID
tags:
- Metadata Templates
x-box-tag: metadata_templates
x-box-sanitized: true
description: Retrieves a metadata template by its ID.
parameters:
- name: template_id
schema:
type: string
required: true
in: path
example: f7a9891f
description: The ID of the template
responses:
'200':
description: Returns the metadata template that matches the ID.
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataTemplate'
'400':
description: >-
Returned if any of the request parameters are not valid.
* `bad_request`: Often returned with a message when the ID of the
template
is not recognised.
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataTemplate'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/metadata_templates/global:
get:
operationId: get_metadata_templates_global
summary: Box List all global metadata templates
tags:
- Metadata Templates
x-box-tag: metadata_templates
x-box-sanitized: true
description: |-
Used to retrieve all generic, global metadata templates available to all
enterprises using Box.
parameters:
- name: marker
description: >-
Defines the position marker at which to begin returning results.
This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
in: query
required: false
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
schema:
type: string
- name: limit
description: The maximum number of items to return per page.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
maximum: 1000
responses:
'200':
description: |-
Returns all of the metadata templates available to all enterprises
and their corresponding schema.
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataTemplates'
'400':
description: Returned when the request parameters are not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/metadata_templates/enterprise:
get:
operationId: get_metadata_templates_enterprise
summary: Box List all metadata templates for enterprise
tags:
- Metadata Templates
x-box-tag: metadata_templates
x-box-sanitized: true
description: >-
Used to retrieve all metadata templates created to be used specifically
within
the user's enterprise
parameters:
- name: marker
description: >-
Defines the position marker at which to begin returning results.
This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
in: query
required: false
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
schema:
type: string
- name: limit
description: The maximum number of items to return per page.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
maximum: 1000
responses:
'200':
description: |-
Returns all of the metadata templates within an enterprise
and their corresponding schema.
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataTemplates'
'400':
description: Returned when the request parameters are not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/metadata_templates/schema:
post:
operationId: post_metadata_templates_schema
summary: Box Create metadata template
tags:
- Metadata Templates
description: |-
Creates a new metadata template that can be applied to
files and folders.
x-box-tag: metadata_templates
x-box-requires-admin: true
x-box-sanitized: true
requestBody:
content:
application/json:
schema:
type: object
required:
- scope
- displayName
properties:
scope:
type: string
description: >-
The scope of the metadata template to create. Applications
can
only create templates for use within the authenticated
user's
enterprise.
This value needs to be set to `enterprise`, as `global`
scopes can
not be created by applications.
example: enterprise
templateKey:
type: string
example: productInfo
description: >-
A unique identifier for the template. This identifier needs
to be
unique across the enterprise for which the metadata template
is
being created.
When not provided, the API will create a unique
`templateKey`
based on the value of the `displayName`.
maxLength: 64
pattern: ^[a-zA-Z_][-a-zA-Z0-9_]*$
displayName:
type: string
description: The display name of the template.
maxLength: 4096
example: Product Info
hidden:
type: boolean
example: true
description: >-
Defines if this template is visible in the Box web app UI,
or if
it is purely intended for usage through the API.
default: false
fields:
type: array
description: >-
An ordered list of template fields which are
# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/metadata-templates-openapi-original.yml