Tag Groups API v2
In Evance, tags are a flexible way to classify and organize content across various resource types, such as Pages and Products. However, before you can assign tags to a resource, you must first define a Tag Group that is scoped to that specific resource type.
What is a Tag Group?
A Tag Group is a container for a set of tags and determines which resources those tags can be applied to. For example, if you want to tag your blog posts, you’ll need to create at least one Tag Group scoped specifically to the Page type (used for blog posts in Evance). Without a Tag Group, tags cannot be applied to that resource.
Most websites use a general-purpose Tag Group simply called "Tag", but you are not limited to just one.
Multiple Tag Groups per resource
Evance allows each resource to be associated with multiple Tag Groups. This provides greater flexibility for organizing content in different ways. For example, a blog post might be tagged under:
- A Topic Tag Group could contain Tags such as Technology, Lifestyle, Health
- A Sector Tag Group could contain Tags such as Education, Retail, Manufacturing
This structure allows developers and content managers to filter, sort, and present tagged content in more meaningful ways across a website.
Scopes
Access to the Tag Groups API requires that the client have the following scopes granted:
-
content- Permits write access to add, update or remove tag groups. -
content.readonly- Read only access to search or get tag group data.
Object structure
JSON example
{
"id": 4684,
"alias": "tags",
"title": "Tags",
"description": null,
"scopes": ["Page"],
"createdOn": "2019-11-09T01:02:00+00:00",
"createdBy": 213,
"modifiedOn": "2019-11-09T01:02:00+00:00",
"modifiedBy": 213
}
List/search Tag Groups
GET
/api/v2/tag-groups.json
Get or search for one or more tag groups using a range of accepted query parameters:
alias:in
Filter results by a comma separated list of aliases. |
id:in
Filter results by a comma separated list of IDs. |
scope:in
Filter results by a comma separated list of scopes. |
Example JSON response
Evance will return a JSON object containing the following properties:
{
"success": true,
"status": 200,
"data": [
{
"id": 4684,
"alias": "tags",
"title": "Tags",
"description": null,
"scopes": ["Page"],
"createdOn": "2019-11-09T01:02:00+00:00",
"createdBy": 213,
"modifiedOn": "2019-11-09T01:02:00+00:00",
"modifiedBy": 213
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 1,
"totalPages": 1
},
"links": {
"self": "https://examples.evance.me/api/v2/tag-groups.json",
"previous": null,
"next": null
}
}
Get a single Tag Group
GET
/api/v2/tag-groups/{id}.json
Retrieve a single Tag Group using its ID.
{
"success": true,
"status": 200,
"data": {
"id", 63456,
"alias": "tag",
"title": "Tags",
"description": null,
"scopes": [
"Page"
],
"createdOn": "2025-01-19T16:45:58+00:00",
"createdBy": 97043,
"modifiedOn": "2025-01-19T16:45:58+00:00",
"modifiedBy": 97043
}
}
Add a Tag Group
POST
/api/v2/tag-groups.json
Adding a new Tag Group has a minimum requirement of title and
scopes, but we recommend also supplying the alias.
POST JSON to this resource within a data object:
{
"data": {
"alias": "tag",
"title": "Tags",
"scopes": [
"Page"
]
}
}
Update a Tag Group
PUT
/api/v2/tag-groups/{id}.json
Updating a Tag Group by its ID requires you to PUT JSON to this resource within a data object:
URL parameters
id
required
The ID of your Tag Group object supplied in the URL. |
Request body
{
"data": {
"description": "Tagged by topic"
}
Delete a Tag Group
DELETE
/api/v2/tag-groups/{id}.json
Deleting a Tag Group by its ID does not require a body. Removing a Tag Group will remove all associated tags.
URL parameters
id
required
The ID of your Tag Group object supplied in the URL. |
Tagging resources with Tag Groups
Managing tags within tag groups has a common pattern across resources and utilises the tag group's alias. The character requirements
for alias means we’re able to use it as a sub-property of a resource’s
tags
property.
{
"data": {
"tags": {
"${alias}": string[]
}
}
Example for a Page resource
{
"data": {
"id": 633286,
...
"tags": {
"topics": ["Technology", "Lifestyle", "Health"],
"sectors": ["Hospitality", "Retail"]
}
}
}
This would require two Tag Groups with aliases topics and sectors, each scoped to the Page resource.
The groups must already exist to assign tags.