---
title: "Create metadata taxonomy"
method: POST
path: "/metadata_taxonomies"
tags: ["Metadata taxonomies"]
---

# Create metadata taxonomy

`POST /metadata_taxonomies`

Creates a new metadata taxonomy that can be used in
metadata templates.

## Request body

- object
  - `key` string — The taxonomy key. If it is not provided in the request body, it will be generated from the `displayName`. The `displayName` would be converted to lower case, and all spaces and non-alphanumeric characters replaced with underscores.
  - `displayName` string, required — The display name of the taxonomy.
  - `namespace` string, required — The namespace of the metadata taxonomy to create.

## Response `201`

The schema representing the metadata taxonomy created.

- MetadataTaxonomy — A taxonomy object for metadata that can be used in metadata templates.
  - `id` string, required — A unique identifier of the metadata taxonomy.
  - `key` string — A unique identifier of the metadata taxonomy. The identifier must be unique within the namespace to which it belongs.
  - `displayName` string, required — The display name of the metadata taxonomy. This can be seen in the Box web app.
  - `namespace` string, required — A namespace that the metadata taxonomy is associated with.
  - `levels` MetadataTaxonomyLevel[] — Levels of the metadata taxonomy.
    - `displayName` string — The display name of the level as it is shown to the user.
    - `description` string — A description of the level.
    - `level` integer — An index of the level within the taxonomy. Levels are indexed starting from 1.

## Other responses

- `400` — Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing.
- `403` — Returned when the user does not have the permission to create the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.
- `default` — An unexpected client error.

---

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