REST API for Content Delivery

Search Published Categories

get

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

Use this query to search published categories. You can control the number of categories to be fetched, paginated, and sorted. Additionally, this resource can fetch field values of matching items.
Query expression syntax supports conditions that match the field values. Query conditions can be joined by using AND/OR operators and grouped with parenthesis. Below are general examples of queries.

Query expression	?q=(name co "car")
Query expression usage with this resource	/published/api/v1.1/taxonomies/{id}/categories?q=(name co "car")

In general one form of filtering is supported by this resource.

Query all categories within a taxonomy: All categories of the taxonomy are queried. However, query conditions are limited to standard fields (id, name, parent.id) and/or optional fields (ancestors.id, ancestors.name, ancestors.apiName).
For example: /published/api/v1.1/taxonomies/{id}/categories?q=(id eq "B0A39B47122C4CE88A6CD52B90C15263")

Operator	Example	Supported data types	Description
eq	q=(id eq "B0A39B47122C4CE88A6CD52B90C15263") q=(name eq "Cars") q=(parent.id eq "C7117D407B1845DEAABBE00526D112FB") q=(ancestors.id eq "C7117D407B1845DEAABBE00526D112FB") q=(ancestors.name eq "car") q=(ancestors.apiName eq "tax-c-c1")	text	Equals operator (eq) matches the exact value supplied in the query. The value provided with this operator is not case-sensitive (name) except for identifier fields (id, parent.id, ancestors.id). This operator considers even special characters in the value.
co	q=(name co "car red") q=(ancestors.name co "car")	text	Contains operator (co) matches every word given in the criteria. It gives the results that have at least one of the words (in this example, car or red or both). This operator does not consider special characters in the value while searching. This operator is applicable to text in case of single-valued attributes. The value provided with this operator is not case-sensitive.
sw	q=(name sw "Car") q=(ancestors.name sw "ca")	text	Starts With operator (sw) matches only the initial character values given in the field condition. The value provided with this operator is not case-sensitive.

Request Headers (Optional):

Header Name	Header Value
channelToken	{valid channel token value}
Accept	application/json

Request

Path Parameters

id: string

Unique identifier (ID) of a taxonomy.

Query Parameters

channelToken(optional): string

Channel token of the publish target. A channel token must be provided as either a query parameter or a request header.
fields(optional): string

The fields parameter is used to control the returned fields and values in the queried category. This parameter accepts a comma-separated list of field names or all. These fields will be returned for each queried category. As all the field names are case-sensitive, users must provide the correct field names in the search query. When fields is specified as all (case-insensitive), all the standard fields and optional fields are returned for each category. Each category has both standard fields (id, name, description, parent) and optional fields (ancestors, children). The standard field id is always returned in the response and cannot be filtered out. This parameter is optional in the query and by default query result shows only id, name and description in the response. Any incorrect or invalid field name given will result in an error.

Example: ?q=(name co "car")&fields=name,description,parent,ancestors
This returns id, name, description, parent and ancestors in the search results for a category containing "car" in the name field.
Example: ?fields=name,parent
This will return only standard fields (such as id, name and parent) for all categories within the default limit.
Example: ?fields=name,children
This will return only id, name and the children count for all categories within the default limit.

Default Value: name,description
limit(optional): integer(int32)

This parameter accepts a non negative integer and is used to control the size of the result. The maximum value allowed for limit is 500.

Default Value: 100
links(optional): string

Accepts a comma-separated list of rel (relation) links, which the client requires in the results. By default, all the applicable links in a resource are included in the response. Possible values are: self, canonical, describedby, first, last, prev, next.
Example: links=self,canonical will only return the links with the rel property self or canonical.
offset(optional): integer(int32)

Start index of response rows.

Default Value: 0
orderBy(optional): string

The orderBy parameter is used to control the order (ascending or descending) of queried items. This parameter is optional in the query and by default there is no order of results. This parameter accepts field names separated by a colon (:), which the user wants to sort the results and sort order.
format: orderBy={fieldName}:{asc/des} (*Note: asc stands for ascending and des for descending. asc and des are always in lower case.)
In a category query, fieldName can be name or position (standard field). When sorting results by position it is important to remember that only searches by parent.id can actually benefit from it. The category position is unique only within a given level or under a given parent category. There will be different categories with the same position value at different levels of the taxonomy. The sort order is optional and by default it is ascending. Any incorrect or invalid field name given will result in an error.

Example: orderBy=name:asc
Returns all categories in ascending order of name.

Example: orderBy=name:des
Returns all categories in descending order of name.

Example: orderBy=position:asc
Returns all categories in ascending order of position.

Example: orderBy=position:des
Returns all categories in descending order of position.
q(optional): string

This parameter accepts a query expression condition that matches the field values. Many such query conditions can be joined using AND/OR operators and grouped with parentheses. The value of query condition follows the format of {fieldName} {operator} "{fieldValue}". The only values allowed in the operator are eq (Equals), co (Contains) and sw (Startswith).
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(name eq "Furnitures")
This will return all categories matching exactly the name "Furnitures".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(name co "chairs" OR name co "red")
This will return all categories containing the words "chairs" or "red".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(name sw "cars")
This will return all categories which name start with "cars".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(apiName eq "cars-apiname")
This will return all categories which apiName matches "cars-apiname".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(id eq "B0A39B47122C4CE88A6CD52B90C15263")
This will return a category with the given identifier.
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.id eq "B0A39B47122C4CE88A6CD52B90C15263")
This will return the categories with an ancestor with the given identifier.
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.name eq "Furnitures")
This will return all categories with an ancestor matching exactly the name "Furnitures".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.name co "chairs" OR ancestors.name co "red")
This will return all categories with an ancestor containing the words "chairs" or "red".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.name sw "cars")
This will return all categories with an ancestor which name starts with "cars".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.apiName eq "cars-apiname")
This will return all categories which apiName matches "cars-apiname".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(parent.id eq "C7117D407B1845DEAABBE00526D112FB")&orderBy=position:asc
This will return all children categories underneath the given parent identifier sorted by their position in ascending order.
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(parent.id eq "C7117D407B1845DEAABBE00526D112FB" AND name co "blue")
This will return all children categories underneath the given parent identifier which contains the word "blue" in their names.
totalResults(optional): boolean

Accepts a Boolean value. Setting it to true displays the total results field in the response.

Default Value: false

Response

Supported Media Types

application/json

200 Response

Successful operation.

Root Schema : CollectionProperties

Type: object

CollectionProperties.

Show Source

aggregationResults(optional): array aggregationResults

Aggregation results.
count(optional): integer(int32)

Total number of records in the current response.
hasMore(optional): boolean

Check whether there are more pages to fetch.
items(optional): array items

Singular resources contained in the collection.
limit(optional): integer(int32)

Actual page size used by the server. This might not be the same as what the client requests.
links(optional): array links

Links of the resource.
offset(optional): integer(int32)

The actual index from which the singular resources are returned.
pinned(optional): array pinned

Pinned items. Shows items pinned at the top of search list
properties(optional): object properties

Additional Properties Allowed: additionalProperties

additional collection properties.
scrollId(optional): string

scrollId if the search resolved to a scroll search.
totalResults(optional): integer(int32)

Total number of rows that satisfy the client request (excluding the paging parameters.)

{
    "type":"object",
    "properties":{
        "hasMore":{
            "type":"boolean",
            "description":"Check whether there are more pages to fetch."
        },
        "offset":{
            "type":"integer",
            "format":"int32",
            "description":"The actual index from which the singular resources are returned."
        },
        "count":{
            "type":"integer",
            "format":"int32",
            "description":"Total number of records in the current response."
        },
        "limit":{
            "type":"integer",
            "format":"int32",
            "description":"Actual page size used by the server. This might not be the same as what the client requests."
        },
        "totalResults":{
            "type":"integer",
            "format":"int32",
            "description":"Total number of rows that satisfy the client request (excluding the paging parameters.)"
        },
        "scrollId":{
            "type":"string",
            "description":"scrollId if the search resolved to a scroll search."
        },
        "properties":{
            "type":"object",
            "description":"additional collection properties.",
            "additionalProperties":{
                "type":"object"
            }
        },
        "items":{
            "type":"array",
            "description":"Singular resources contained in the collection.",
            "items":{
                "type":"object"
            }
        },
        "aggregationResults":{
            "type":"array",
            "description":"Aggregation results.",
            "items":{
                "$ref":"#/definitions/AggregationResult"
            }
        },
        "links":{
            "type":"array",
            "description":"Links of the resource.",
            "items":{
                "$ref":"#/definitions/Link"
            }
        },
        "pinned":{
            "type":"array",
            "description":"Pinned items. Shows items pinned at the top of search list",
            "items":{
                "type":"string"
            }
        }
    },
    "description":"CollectionProperties."
}

Nested Schema : aggregationResults

Type: array

Aggregation results.

Show Source

Array of: object AggregationResult

{
    "type":"array",
    "description":"Aggregation results.",
    "items":{
        "$ref":"#/definitions/AggregationResult"
    }
}

Nested Schema : items

Type: array

Singular resources contained in the collection.

Show Source

Array of: object items

{
    "type":"array",
    "description":"Singular resources contained in the collection.",
    "items":{
        "type":"object"
    }
}

Nested Schema : links

Type: array

Links of the resource.

Show Source

Array of: object Link

Link of the resource.

{
    "type":"array",
    "description":"Links of the resource.",
    "items":{
        "$ref":"#/definitions/Link"
    }
}

Nested Schema : pinned

Type: array

Pinned items. Shows items pinned at the top of search list

Show Source

Array of: string

{
    "type":"array",
    "description":"Pinned items. Shows items pinned at the top of search list",
    "items":{
        "type":"string"
    }
}

Nested Schema : properties

Type: object

Additional Properties Allowed

Show Source

object additionalProperties

{
    "type":"object",
    "description":"additional collection properties.",
    "additionalProperties":{
        "type":"object"
    }
}

additional collection properties.

Nested Schema : AggregationResult

Type: object

Show Source

name(optional): string

Read Only: true

{
    "type":"object",
    "properties":{
        "name":{
            "type":"string",
            "readOnly":true
        }
    }
}

Nested Schema : items

Type: object

Nested Schema : Link

Type: object

Link of the resource.

Show Source

href(optional): string

The target resource's URI. It could be template URI. It is a required property in the get response.
mediaType(optional): string

Media type.
method(optional): string

What HTTP method can be used to access the target resource.
profile(optional): string

Link to the metadata that describes the target resource.
rel(optional): string

Relation type. It is a required property in the get response.
templated(optional): boolean

Whether the URI is a template.

{
    "type":"object",
    "properties":{
        "href":{
            "type":"string",
            "description":"The target resource's URI. It could be template URI. It is a required property in the get response."
        },
        "rel":{
            "type":"string",
            "description":"Relation type. It is a required property in the get response."
        },
        "templated":{
            "type":"boolean",
            "description":"Whether the URI is a template."
        },
        "method":{
            "type":"string",
            "description":"What HTTP method can be used to access the target resource."
        },
        "profile":{
            "type":"string",
            "description":"Link to the metadata that describes the target resource."
        },
        "mediaType":{
            "type":"string",
            "description":"Media type."
        }
    },
    "description":"Link of the resource."
}

Nested Schema : additionalProperties

Type: object

400 Response

Bad Request. The server is unable to process the request on the client side due to malformed syntax, invalid data or message framing.

403 Response

Forbidden. Client is not authorized to perform this request.

500 Response

Internal server error. An unexpected error condition encountered in the system.

Examples

The following example shows how to search published taxonomy categories.

curl -i -X GET -H "Accept:application/json" 'http://<hostname>/content/published/api/v1.1/taxonomies/{id}/categories'

Example 1

Searches published taxonomy category with taxonomy id: 26950D77A5654D8BA407AC9F7DBCFF1F, having category id: 2069018ECE874C2DAA4051E9C16AD244 with channelToken: 1a3885a5a75b40baafe6495eb0b1125b.

/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=%28+id+eq+%222069018ECE874C2DAA4051E9C16AD244%22%29&totalResults=true&offset=0&orderBy=name%3Aasc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all

Response Body

{
        ody": {
        "hasMore": false,
        "offset": 0,
        "count": 1,
        "limit": 1,
        "totalResults": 1,
        "items": [
          {
            "apiName": "t31-c-c-c1",
            "id": "2069018ECE874C2DAA4051E9C16AD244",
            "name": "car red medium",
            "description": "car red medium description",
            "position": 1,
            "parent": {
              "id": "50AE00A8234B4AE1B675D36989F8B9CF",
              "name": "car red",
              "apiName": "t31-c-c"
            },
            "ancestors": [
              {
                "id": "6775D3D56E184CC3B8EC59A32AF1DD73",
                "name": "car",
                "apiName": "t31-c"
              },
              {
                "id": "50AE00A8234B4AE1B675D36989F8B9CF",
                "name": "car red",
                "apiName": "t31-c-c"
              }
            ],
            "links": [
              {
                "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories/2069018ECE874C2DAA4051E9C16AD244?channelToken=1a3885a5a75b40baafe6495eb0b1125b",
                "rel": "self",
                "method": "GET",
                "mediaType": "application/json"
              }
            ]
          }
        ],
        "links": [
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( id eq \"2069018ECE874C2DAA4051E9C16AD244\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "self",
            "method": "GET",
            "mediaType": "application/json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( id eq \"2069018ECE874C2DAA4051E9C16AD244\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "canonical",
            "method": "GET",
            "mediaType": "application/json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/metadata-catalog/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?channelToken=1a3885a5a75b40baafe6495eb0b1125b",
            "rel": "describedby",
            "method": "GET",
            "mediaType": "application/schema+json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( id eq \"2069018ECE874C2DAA4051E9C16AD244\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "first",
            "method": "GET",
            "mediaType": "application/json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( id eq \"2069018ECE874C2DAA4051E9C16AD244\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "last",
            "method": "GET",
            "mediaType": "application/json"
          }

Example 2

This searches published taxonomy categories with taxonomy id: 26950D77A5654D8BA407AC9F7DBCFF1F, with category name equals to car blue with channelToken:1a3885a5a75b40baafe6495eb0b1125b

/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=%28+name+eq+%22car+blue%22%29&totalResults=true&offset=0&orderBy=name%3Aasc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all

Response Body

{
        "hasMore": false,
        "offset": 0,
        "count": 1,
        "limit": 1,
        "totalResults": 1,
        "items": [
          {
            "apiName": "t31-car-blue-26950d77a5654d8ba407ac9f7dbcff1f",
            "id": "5096C5762F9540BCB23AA13001CA872E",
            "name": "car blue",
            "description": "car description",
            "position": 1,
            "parent": {
              "id": "6775D3D56E184CC3B8EC59A32AF1DD73",
              "name": "car",
              "apiName": "t31-c"
            },
            "ancestors": [
              {
                "id": "6775D3D56E184CC3B8EC59A32AF1DD73",
                "name": "car",
                "apiName": "t31-c"
              }
            ],
            "links": [
              {
                "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories/5096C5762F9540BCB23AA13001CA872E?channelToken=1a3885a5a75b40baafe6495eb0b1125b",
                "rel": "self",
                "method": "GET",
                "mediaType": "application/json"
              }
            ]
          }
        ],
        "links": [
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( name eq \"car blue\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "self",
            "method": "GET",
            "mediaType": "application/json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( name eq \"car blue\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "canonical",
            "method": "GET",
            "mediaType": "application/json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/metadata-catalog/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?channelToken=1a3885a5a75b40baafe6495eb0b1125b",
            "rel": "describedby",
            "method": "GET",
            "mediaType": "application/schema+json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( name eq \"car blue\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "first",
            "method": "GET",
            "mediaType": "application/json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( name eq \"car blue\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "last",
            "method": "GET",
            "mediaType": "application/json"
          }
        ]
      }
    }
  ]