Create a category

post

/content/management/api/v1.1/taxonomies/{id}/categories

with given payload and attach it to the provided parent.

Request

Supported Media Types
Path Parameters
Query Parameters
Header Parameters
Body ()
Creates a category with the given information in the payload. The fields id, children, idPath, namePath and links will be ignored even if given in the payload.

The parentId when provided will attach the category to the category with that id. To create a 1st level category, the parentId should be set to the taxonomy id. The parentId cannot be empty when creating a category.

The position field can be used to specify the order of the category among its siblings. If no position is provided the category will be placed last among its siblings.

The apiName field uniquely identifies the category across all taxonomies. This field is case insensitive. It will be automatically prefixed with the unique taxonomy shortName in case the payload does not have it already.

Example: Creating a category with apiName. All whitespace characters will be trimmed by the server. Note that taxonomy shortName will also be added as prefix of the apiName value in the payload.
  • taxonomy shortName = "TAX"
  • apiName = "My API name value"
  • Result apiName = "tax-my-api-name-value"

Example: Creating a category without apiName. Server will automatically generate apiName using the taxonomy shortName prefix followed by the first character of each ancestors of this category.
  • taxonomy shortName = "VEH"
  • category name = "Red"
  • ancestors names = "Vehicles", "Cars" and "Sport"
  • Result apiName = "veh-v-c-s-r"

Example: Creating a category without apiName having a conflict. Server will automatically generate apiName using the taxonomy shortName prefix followed by the first character of each ancestors of this category. A numeric suffix will be added in case of any conflicts with other values.
  • taxonomy shortName = "VEH"
  • category name = "Red Wine"
  • ancestors names = "Vehicles", "Cars" and "Sport"
  • Result apiName = "veh-v-c-s-r1"


The synonyms field is a comma-separated list of values that will be assigned to the synonyms system managed category property of the taxonomy.

The keywords field is a comma-separated list of values that will be assigned to the keywords system managed category property of the taxonomy.

The relatedCategories field is a list where each element represents a category that will be related to the current category, and these values will be assigned to the relatedCategories system managed category property of the taxonomy.

The customProperties field represents the property values for the user defined category properties. To assign values for a specific custom category property you must provide the apiName of the category property followed by the list of values. If no value is provided for an existing custom category property, server will assign the default values of the category property automatically.
Root Schema : CategoryInformation
Type: object
Category Information
Show Source
Nested Schema : ancestors
Type: array
The ancestors of the Category. First element represents the root category and the last element represents the immediate parent of the category.
Show Source
Nested Schema : CollectionPropertiesCategoryInCollection
Type: object
CollectionProperties.
Show Source
Nested Schema : customProperties
Type: object
Additional Properties Allowed
Show Source
The custom properties' values of the Category.
Nested Schema : keywords
Type: array
The keywords of the Category.
Show Source
Nested Schema : CategoryAncestorBean
Type: object
Show Source
Nested Schema : relatedCategories
Type: array
The related categories of the Category.
Show Source
Nested Schema : ItemSubResourceListItem
Type: object
Item SubResource.
Show Source
Nested Schema : synonyms
Type: array
The synonyms of the Category.
Show Source
Nested Schema : aggregationResults
Type: array
Aggregation results.
Show Source
Nested Schema : items
Type: array
Singular resources contained in the collection.
Show Source
Nested Schema : pinned
Type: array
Pinned items. Shows items pinned at the top of search list
Show Source
Nested Schema : AggregationResult
Type: object
Show Source
Nested Schema : CategoryInCollection
Type: object
Category in Collection Response
Show Source
Nested Schema : customProperties
Type: object
Additional Properties Allowed
Show Source
The custom properties' values of the Category.
Nested Schema : keywords
Type: array
The keywords of the Category.
Show Source
Nested Schema : relatedCategories
Type: array
The related categories of the Category.
Show Source
Nested Schema : synonyms
Type: array
The synonyms of the Category.
Show Source
Nested Schema : CustomPropertyValuesBean
Type: object
Show Source
Nested Schema : values
Type: array
The list of values of the custom property.
Show Source
Nested Schema : CustomPropertyValue
Type: object
Show Source
Nested Schema : RelatedCategory
Type: object
Related Category
Show Source
Nested Schema : nodes
Type: array
The path of the category.
Show Source
Nested Schema : RelatedTaxonomyBean
Type: object
Show Source
Nested Schema : CategoryNodeBean
Type: object
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : Item
Type: object
Discriminator: typeCategory
Item
Show Source
Nested Schema : ItemSubResourceListChangesInfo
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListChannelId
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListCollectionId
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceConnectorFileInfo
Type: object
Item SubResource.
Show Source
Nested Schema : User
Type: object
User object
Show Source
Nested Schema : date
Type: object
date
Show Source
Nested Schema : fields
Type: object
Read Only: true
Additional Properties Allowed
Show Source
User-defined fields data. Map. All the user-defined fields required in the type definition must be provided under this property in PUT and POST request.
Nested Schema : ItemSubResourceLockInfo
Type: object
Item SubResource.
Show Source
Nested Schema : ItemMetadataInfo
Type: object
ItemMetadataInfo
Show Source
Nested Schema : ItemSubResourceListAction
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListPublishInfo
Type: object
Item SubResource.
Show Source
Nested Schema : ItemReferenceInfo
Type: object
ItemReferenceInfo
Show Source
Nested Schema : ItemSubResourceRelationships
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListSuggestedTaxonomyInfo
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListTag
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListTaxonomyInfo
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListVariationsInfo
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListVersionInfo
Type: object
Item SubResource.
Show Source
Nested Schema : VideoBean
Type: object
VideoBean
Show Source
Nested Schema : WorkflowField
Type: object
All mapped workflow fields
Show Source
Nested Schema : ItemSubResourceListWorkflowInfo
Type: object
Item SubResource.
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : ChangesInfo
Type: object
ChangesInfo
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : ChannelId
Type: object
ChannelId
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : CollectionId
Type: object
CollectionId
Show Source
Nested Schema : ConnectorFileInfo
Type: object
ConnectorFileInfo
Show Source
Nested Schema : additionalProperties
Type: object
Nested Schema : LockInfo
Type: object
LockInfo
Show Source
Nested Schema : EXIFMetadata
Type: object
EXIF Metadata
Show Source
Nested Schema : VideoTranscriptMetadata
Type: object
Video Transcription Metadata
Show Source
Nested Schema : aggregationResults
Type: array
Aggregation results.
Show Source
Nested Schema : items
Type: array
Singular resources contained in the collection.
Show Source
Nested Schema : pinned
Type: array
Pinned items. Shows items pinned at the top of search list
Show Source
Nested Schema : ItemExtractedExifBean
Type: object
ItemExtractedExifBean
Show Source
Nested Schema : aggregationResults
Type: array
Aggregation results.
Show Source
Nested Schema : items
Type: array
Singular resources contained in the collection.
Show Source
Nested Schema : pinned
Type: array
Pinned items. Shows items pinned at the top of search list
Show Source
Nested Schema : Videotranscript
Type: object
Video transcript
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : Action
Type: object
Action
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : PublishInfo
Type: object
PublishInfo
Show Source
Nested Schema : Relationships
Type: object
Relationships
Show Source
Nested Schema : referencedBy
Type: array
Referenced by ids
Show Source
Nested Schema : Siteplanreference
Type: object
Site plan reference
Show Source
Nested Schema : referencedBySites
Type: array
Referenced by sites
Show Source
Nested Schema : references
Type: array
Reference ids
Show Source
Nested Schema : References
Type: object
References
Show Source
Nested Schema : ReferencedBySites
Type: object
ReferencedBySites
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : SuggestedTaxonomyInfo
Type: object
SuggestedTaxonomyInfo
Show Source
Nested Schema : categories
Type: array
Categories in the Suggested Taxonomy the item belongs to.
Show Source
Nested Schema : ItemSuggestedCategoryInfo
Type: object
Show Source
Nested Schema : nodes
Type: array
Nodes in the category assigned to the item.
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : Tag
Type: object
Tag.
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : TaxonomyInfo
Type: object
TaxonomyInfo
Show Source
Nested Schema : categories
Type: array
Categories in the Taxonomy the item belongs to.
Show Source
Nested Schema : ItemCategoryInfo
Type: object
Show Source
Nested Schema : nodes
Type: array
Nodes in the category assigned to the item.
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : VariationsInfo
Type: object
Variations Info.
Show Source
Nested Schema : items
Type: array
Content item variations.
Show Source
Nested Schema : Language
Type: object
LanguageItem
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : VersionInfo
Type: object
VersionInfo
Show Source
Nested Schema : PlaybackBean
Type: object
PlaybackBean
Show Source
Nested Schema : ProcessingBean
Type: object
ProcessingBean
Show Source
  • Read Only: true
    The progress of the background process. The value of this field will be one of PENDING, SUCCEEDED or FAILED.
Nested Schema : StripBean
Type: object
StripBean
Show Source
Nested Schema : AdaptiveStreamsBean
Type: object
AdaptiveStreamsBean
Show Source
Nested Schema : StripFrameBean
Type: object
StripFrameBean
Show Source
Nested Schema : aggregationResults
Type: array
Aggregation results.
Show Source
Nested Schema : items
Type: array
Singular resources contained in the collection.
Show Source
Nested Schema : pinned
Type: array
Pinned items. Shows items pinned at the top of search list
Show Source
Nested Schema : WorkflowInfo
Type: object
WorkflowInfo.
Show Source
Nested Schema : data
Type: array
Show Source
Back to Top

Response

Supported Media Types

201 Response

Created.
Body ()
Root Schema : CategoryInformation
Type: object
Category Information
Show Source
Nested Schema : ancestors
Type: array
The ancestors of the Category. First element represents the root category and the last element represents the immediate parent of the category.
Show Source
Nested Schema : CollectionPropertiesCategoryInCollection
Type: object
CollectionProperties.
Show Source
Nested Schema : customProperties
Type: object
Additional Properties Allowed
Show Source
The custom properties' values of the Category.
Nested Schema : keywords
Type: array
The keywords of the Category.
Show Source
Nested Schema : CategoryAncestorBean
Type: object
Show Source
Nested Schema : relatedCategories
Type: array
The related categories of the Category.
Show Source
Nested Schema : ItemSubResourceListItem
Type: object
Item SubResource.
Show Source
Nested Schema : synonyms
Type: array
The synonyms of the Category.
Show Source
Nested Schema : aggregationResults
Type: array
Aggregation results.
Show Source
Nested Schema : items
Type: array
Singular resources contained in the collection.
Show Source
Nested Schema : pinned
Type: array
Pinned items. Shows items pinned at the top of search list
Show Source
Nested Schema : AggregationResult
Type: object
Show Source
Nested Schema : CategoryInCollection
Type: object
Category in Collection Response
Show Source
Nested Schema : customProperties
Type: object
Additional Properties Allowed
Show Source
The custom properties' values of the Category.
Nested Schema : keywords
Type: array
The keywords of the Category.
Show Source
Nested Schema : relatedCategories
Type: array
The related categories of the Category.
Show Source
Nested Schema : synonyms
Type: array
The synonyms of the Category.
Show Source
Nested Schema : CustomPropertyValuesBean
Type: object
Show Source
Nested Schema : values
Type: array
The list of values of the custom property.
Show Source
Nested Schema : CustomPropertyValue
Type: object
Show Source
Nested Schema : RelatedCategory
Type: object
Related Category
Show Source
Nested Schema : nodes
Type: array
The path of the category.
Show Source
Nested Schema : RelatedTaxonomyBean
Type: object
Show Source
Nested Schema : CategoryNodeBean
Type: object
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : Item
Type: object
Discriminator: typeCategory
Item
Show Source
Nested Schema : ItemSubResourceListChangesInfo
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListChannelId
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListCollectionId
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceConnectorFileInfo
Type: object
Item SubResource.
Show Source
Nested Schema : User
Type: object
User object
Show Source
Nested Schema : date
Type: object
date
Show Source
Nested Schema : fields
Type: object
Read Only: true
Additional Properties Allowed
Show Source
User-defined fields data. Map. All the user-defined fields required in the type definition must be provided under this property in PUT and POST request.
Nested Schema : ItemSubResourceLockInfo
Type: object
Item SubResource.
Show Source
Nested Schema : ItemMetadataInfo
Type: object
ItemMetadataInfo
Show Source
Nested Schema : ItemSubResourceListAction
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListPublishInfo
Type: object
Item SubResource.
Show Source
Nested Schema : ItemReferenceInfo
Type: object
ItemReferenceInfo
Show Source
Nested Schema : ItemSubResourceRelationships
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListSuggestedTaxonomyInfo
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListTag
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListTaxonomyInfo
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListVariationsInfo
Type: object
Item SubResource.
Show Source
Nested Schema : ItemSubResourceListVersionInfo
Type: object
Item SubResource.
Show Source
Nested Schema : VideoBean
Type: object
VideoBean
Show Source
Nested Schema : WorkflowField
Type: object
All mapped workflow fields
Show Source
Nested Schema : ItemSubResourceListWorkflowInfo
Type: object
Item SubResource.
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : ChangesInfo
Type: object
ChangesInfo
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : ChannelId
Type: object
ChannelId
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : CollectionId
Type: object
CollectionId
Show Source
Nested Schema : ConnectorFileInfo
Type: object
ConnectorFileInfo
Show Source
Nested Schema : additionalProperties
Type: object
Nested Schema : LockInfo
Type: object
LockInfo
Show Source
Nested Schema : EXIFMetadata
Type: object
EXIF Metadata
Show Source
Nested Schema : VideoTranscriptMetadata
Type: object
Video Transcription Metadata
Show Source
Nested Schema : aggregationResults
Type: array
Aggregation results.
Show Source
Nested Schema : items
Type: array
Singular resources contained in the collection.
Show Source
Nested Schema : pinned
Type: array
Pinned items. Shows items pinned at the top of search list
Show Source
Nested Schema : ItemExtractedExifBean
Type: object
ItemExtractedExifBean
Show Source
Nested Schema : aggregationResults
Type: array
Aggregation results.
Show Source
Nested Schema : items
Type: array
Singular resources contained in the collection.
Show Source
Nested Schema : pinned
Type: array
Pinned items. Shows items pinned at the top of search list
Show Source
Nested Schema : Videotranscript
Type: object
Video transcript
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : Action
Type: object
Action
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : PublishInfo
Type: object
PublishInfo
Show Source
Nested Schema : Relationships
Type: object
Relationships
Show Source
Nested Schema : referencedBy
Type: array
Referenced by ids
Show Source
Nested Schema : Siteplanreference
Type: object
Site plan reference
Show Source
Nested Schema : referencedBySites
Type: array
Referenced by sites
Show Source
Nested Schema : references
Type: array
Reference ids
Show Source
Nested Schema : References
Type: object
References
Show Source
Nested Schema : ReferencedBySites
Type: object
ReferencedBySites
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : SuggestedTaxonomyInfo
Type: object
SuggestedTaxonomyInfo
Show Source
Nested Schema : categories
Type: array
Categories in the Suggested Taxonomy the item belongs to.
Show Source
Nested Schema : ItemSuggestedCategoryInfo
Type: object
Show Source
Nested Schema : nodes
Type: array
Nodes in the category assigned to the item.
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : Tag
Type: object
Tag.
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : TaxonomyInfo
Type: object
TaxonomyInfo
Show Source
Nested Schema : categories
Type: array
Categories in the Taxonomy the item belongs to.
Show Source
Nested Schema : ItemCategoryInfo
Type: object
Show Source
Nested Schema : nodes
Type: array
Nodes in the category assigned to the item.
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : VariationsInfo
Type: object
Variations Info.
Show Source
Nested Schema : items
Type: array
Content item variations.
Show Source
Nested Schema : Language
Type: object
LanguageItem
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : VersionInfo
Type: object
VersionInfo
Show Source
Nested Schema : PlaybackBean
Type: object
PlaybackBean
Show Source
Nested Schema : ProcessingBean
Type: object
ProcessingBean
Show Source
  • Read Only: true
    The progress of the background process. The value of this field will be one of PENDING, SUCCEEDED or FAILED.
Nested Schema : StripBean
Type: object
StripBean
Show Source
Nested Schema : AdaptiveStreamsBean
Type: object
AdaptiveStreamsBean
Show Source
Nested Schema : StripFrameBean
Type: object
StripFrameBean
Show Source
Nested Schema : aggregationResults
Type: array
Aggregation results.
Show Source
Nested Schema : items
Type: array
Singular resources contained in the collection.
Show Source
Nested Schema : pinned
Type: array
Pinned items. Shows items pinned at the top of search list
Show Source
Nested Schema : WorkflowInfo
Type: object
WorkflowInfo.
Show Source
Nested Schema : data
Type: array
Show Source

400 Response

Bad request.

403 Response

Forbidden.

404 Response

Taxonomy not found. The requested resource not found.

409 Response

The requested resource operation is temporarily unavailable

500 Response

Internal server error.
Back to Top

Examples

The following examples show how to create taxonomy categories by submitting a POST request on the REST resource using cURL:

curl -X POST -H 'Content-Type: application/json' -H 'X-Requested-With: XMLHttpRequest' 'https://host:port/content/management/api/v1.1/taxonomies/{id}/categories'

Example 1:

This example shows how to add a root category with the name C5 to the taxonomy. The parentId specified is the ID of the taxonomy.

/content/management/api/v1.1/taxonomies/D7969D6CA0D144AEA9CCA88BA6D2CF81/categories

Request Body

{
   "name": "C5",
   "parentId": "D7969D6CA0D144AEA9CCA88BA6D2CF81"
}

Example 2:

This example shows how to add a root category to the taxonomy with a description and name.

/content/management/api/v1.1/taxonomies/D7969D6CA0D144AEA9CCA88BA6D2CF81/categories

Request Body

{
  "name": "C6",
  "parentId": "D7969D6CA0D144AEA9CCA88BA6D2CF81",
  "description": "The description info"
}

Example 3:

This example shows how to add a category at the last position (default) under the parent category by specifying the parent ID.

/content/management/api/v1.1/taxonomies/D7969D6CA0D144AEA9CCA88BA6D2CF81/categories

Request Body

{
   "name": "C6.1",
   "parentId": "6F81E244EB8D4E229CBF00A065009598",
   "description": "The description info"
}

Example 4:

This example shows how to add a category at position 0 (front) under the parent category by specifying the parent ID.

/content/management/api/v1.1/taxonomies/D7969D6CA0D144AEA9CCA88BA6D2CF81/categories

Request Body

{
   "name": "C6.0",
   "parentId": "6F81E244EB8D4E229CBF00A065009598",
   "position": 0
}
Back to Top