# Tag

A *Tag* is a short label that classifies *Content* or *Media*. Take a clothing store as an example: labels like "Bestsellers" and "New arrivals" are *Tag*s. If you attach the same *Tag* to several *Content* or *Media*, you can later read or pick them out grouped by that label.

A *Tag* itself is a label that has only a name (`name`), and it is a settings resource with no publishing concept. Attaching it to something is not done by editing the *Tag* directly. Instead, you put this *Tag*'s `Refer` into the `metadata.tags` of a *Content* or *Media* (see [Attaching Tags to Content and Media](#attaching-tags-to-content-and-media) below). In CMA, a *Tag* is a sub-resource of *Space*, and its path is based on `/spaces/{spaceId}/tags`.

## Resource structure {#resource-structure}

The following is the single-read response for the *Tag* "Bestsellers". It has `sys` (system properties) and the body property `name`.

```json
{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7PLeuQQPP9Oe",
    "type": "Tag",
    "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-16T01:46:07.426Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-16T01:46:07.426Z",
    "version": 1
  },
  "name": "Bestsellers"
}
```

Key properties:

- `sys.id`: The unique identifier of the *Tag*. It goes into `{tagId}` in the single-read, update, and delete paths, and it is also used as the `Refer` target id when you attach the tag via `metadata.tags`.
- `name`: The name of the *Tag* (1-16 characters). It is the label itself that appears in content classification.

## System properties (sys) {#system-properties-sys}

Every *Tag* carries common system properties in the `sys` object. `space`, `createdBy`, and `updatedBy` are in the `Refer` shape (`{ "sys": { "id", "type": "Refer", "targetType" } }`).

| Property | Type | Description |
|---|---|---|
| `id` | string | Unique resource identifier. |
| `type` | string | Resource kind. For a *Tag* this is always `"Tag"`. |
| `space` | Refer<Space> | The *Space* this *Tag* belongs to. |
| `createdBy` | Refer<User> | The user who created it. |
| `createdAt` | string (date-time) | Creation time. |
| `updatedBy` | Refer<User> | The user who last updated it. |
| `updatedAt` | string (date-time) | Last update time. |
| `version` | integer (≥1) | Resource version. It increases by 1 with every change. |

Body property:

| Property | Type | Description |
|---|---|---|
| `name` | string (1-16) | The *Tag* name. Specified on create and update. |

A *Tag* is a settings resource with no publishing concept. So unlike *Content* and *Media*, its `sys` has no `publish`, `archive`, or `status`, only `version`. The `version` increases each time you update the *Tag*.

## Attaching Tags to Content and Media {#attaching-tags-to-content-and-media}

Attaching a *Tag* takes two steps.

1. Create the *Tag* (the [Create Tag](#api) endpoint below). Keep the `sys.id` from the response.
2. When you create or edit a *Content* or *Media*, put this *Tag*'s `Refer` into the `metadata.tags` array of its body.

The shape of the `Refer` you put into `metadata.tags` is as follows. Into `id` you put the `sys.id` of the *Tag* you obtained in step 1.

```json
"metadata": {
  "tags": [
    { "sys": { "id": "3trmXRM3RqbgSnifyg7PLeuQQPP9Oe", "type": "Refer", "targetType": "Tag" } }
  ]
}
```

To attach several *Tag*s, put multiple of these `Refer` objects in the array. To remove a tag, drop the matching entry from the array and update the *Content* or *Media* again. For the detailed way to author *Content* and *Media* body data, see the [Content](/api/reference/cma/content.md) and [Media](/api/reference/cma/media.md) documents.

## API {#api}

The base URL for all endpoints below is `https://cma.weegloo.com/v1`, and a Bearer token that authenticates against CMA is required in the `Authorization` header. Update and partial update must also send the `X-Weegloo-Version` header (the current resource's `sys.version`) for optimistic concurrency control. Create and delete do not have this header.

```api-endpoint
{
  "title": "List Tags",
  "method": "GET",
  "path": "/spaces/{spaceId}/tags",
  "description": "Reads the list of Tags in a Space, page by page.",
  "responseStatus": 200,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true }
  },
  "queryParameterSchema": {
    "limit": { "type": "integer", "description": "Number of items to return per page (1-100)", "default": 15 },
    "skip": { "type": "integer", "description": "Number of items to skip", "default": 0 },
    "next": { "type": "string", "description": "Next page cursor (the value obtained from links.next in the previous response)" },
    "prev": { "type": "string", "description": "Previous page cursor (the value obtained from links.prev in the previous response)" },
    "order": { "type": "string", "description": "Sort criteria. Comma-separated for multi-level sorting (e.g. sys.createdAt,sys.id)", "default": "sys.createdAt,sys.id" },
    "select": { "type": "string", "description": "Fields to include (sys.id,sys.createdAt) or exclude (-sys.id). Do not mix include and exclude." },
    "include": { "type": "integer", "description": "Related-resource inclusion level. 0=default, 1=related resources, 2=nested relations, 3=full", "default": 0 }
  },
  "additionalQueryParams": true,
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }
  },
  "responseExample": {
    "sys": { "type": "TotalPageResponse" },
    "limit": 15,
    "totalCount": 1,
    "items": [
      {
        "sys": {
          "id": "3trmXRM3RqbgSnifyg7PLeuQQPP9Oe",
          "type": "Tag",
          "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } },
          "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
          "createdAt": "2026-06-16T01:46:07.426Z",
          "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
          "updatedAt": "2026-06-16T01:46:07.426Z",
          "version": 1
        },
        "name": "Bestsellers"
      }
    ],
    "links": { "self": "/v1/spaces/tcq4V2Xb/tags" }
  }
}
```

```api-endpoint
{
  "title": "Read a single Tag",
  "method": "GET",
  "path": "/spaces/{spaceId}/tags/{tagId}",
  "description": "Reads one Tag by sys.id.",
  "responseStatus": 200,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true },
    "tagId": { "type": "string", "description": "The sys.id of the Tag", "required": true }
  },
  "queryParameterSchema": {
    "include": { "type": "integer", "description": "Related-resource inclusion level. 0=default, 1=related resources, 2=nested relations, 3=full", "default": 0 }
  },
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }
  },
  "responseExample": {
    "sys": {
      "id": "3trmXRM3RqbgSnifyg7PLeuQQPP9Oe",
      "type": "Tag",
      "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } },
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-06-16T01:46:07.426Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-06-16T01:46:07.426Z",
      "version": 1
    },
    "name": "Bestsellers"
  }
}
```

```api-endpoint
{
  "title": "Create Tag",
  "method": "POST",
  "path": "/spaces/{spaceId}/tags",
  "description": "Creates a new Tag in a Space. The body holds only name. Keep the sys.id from the response to use it when attaching the tag to Content or Media via metadata.tags.",
  "responseStatus": 201,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true }
  },
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }
  },
  "requestBodySchema": {
    "type": "object",
    "required": ["name"],
    "properties": {
      "name": { "type": "string", "minLength": 1, "maxLength": 16, "description": "The Tag name (1-16 characters)" }
    },
    "example": {
      "name": "New arrivals"
    }
  },
  "responseExample": {
    "sys": {
      "id": "3trmXRM3RqbgSnifyg7PLewNewArr1",
      "type": "Tag",
      "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } },
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-06-18T10:28:11.263Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-06-18T10:28:11.263Z",
      "version": 1
    },
    "name": "New arrivals"
  }
}
```

```api-endpoint
{
  "title": "Update Tag",
  "method": "PUT",
  "path": "/spaces/{spaceId}/tags/{tagId}",
  "description": "Updates the Tag's name. The body holds only name. You must carry the current sys.version in the X-Weegloo-Version header.",
  "responseStatus": 200,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true },
    "tagId": { "type": "string", "description": "The sys.id of the Tag", "required": true }
  },
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" },
    "X-Weegloo-Version": { "type": "integer", "description": "The current resource's sys.version (optimistic concurrency control)" }
  },
  "requestBodySchema": {
    "type": "object",
    "required": ["name"],
    "properties": {
      "name": { "type": "string", "minLength": 1, "maxLength": 16, "description": "The Tag name (1-16 characters)" }
    },
    "example": {
      "name": "New arrivals in"
    }
  },
  "responseExample": {
    "sys": {
      "id": "3trmXRM3RqbgSnifyg7PLewNewArr1",
      "type": "Tag",
      "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } },
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-06-18T10:28:11.263Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-06-18T10:28:20.000Z",
      "version": 2
    },
    "name": "New arrivals in"
  }
}
```

```api-endpoint
{
  "title": "Partially update Tag (JSON Patch)",
  "method": "PATCH",
  "path": "/spaces/{spaceId}/tags/{tagId}",
  "description": "Updates only part of a Tag (name) using RFC 6902 JSON Patch. The request Content-Type header must be application/json-patch+json. You must carry the current sys.version in the X-Weegloo-Version header.",
  "responseStatus": 200,
  "baseUrl": "https://cma.weegloo.com/v1",
  "requestContentType": "application/json-patch+json",
  "pathParameterSchema": {
    "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true },
    "tagId": { "type": "string", "description": "The sys.id of the Tag", "required": true }
  },
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" },
    "Content-Type": { "type": "string", "description": "application/json-patch+json (RFC 6902 JSON Patch)" },
    "X-Weegloo-Version": { "type": "integer", "description": "The current resource's sys.version (optimistic concurrency control)" }
  },
  "requestBodySchema": {
    "type": "array",
    "description": "An array of RFC 6902 JSON Patch operations (op / path / value / from). path is an RFC 6901 JSON Pointer.",
    "items": {
      "type": "object",
      "required": ["op", "path"],
      "properties": {
        "op": { "type": "string", "enum": ["add", "remove", "replace", "move", "copy", "test"], "description": "Operation kind" },
        "path": { "type": "string", "description": "Target location (JSON Pointer). Example: /name" },
        "value": { "description": "The value used by add/replace/test" },
        "from": { "type": "string", "description": "The source location for move/copy" }
      }
    },
    "example": [
      { "op": "replace", "path": "/name", "value": "New arrivals" }
    ]
  },
  "responseExample": {
    "sys": {
      "id": "3trmXRM3RqbgSnifyg7PLewNewArr1",
      "type": "Tag",
      "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } },
      "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "createdAt": "2026-06-18T10:28:11.263Z",
      "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
      "updatedAt": "2026-06-18T10:28:25.000Z",
      "version": 3
    },
    "name": "New arrivals"
  }
}
```

```api-endpoint
{
  "title": "Delete Tag",
  "method": "DELETE",
  "path": "/spaces/{spaceId}/tags/{tagId}",
  "description": "Deletes a Tag. On success it responds with 204 No Content and no response body.",
  "responseStatus": 204,
  "baseUrl": "https://cma.weegloo.com/v1",
  "pathParameterSchema": {
    "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true },
    "tagId": { "type": "string", "description": "The sys.id of the Tag", "required": true }
  },
  "requestHeaderSchema": {
    "Authorization": { "type": "string", "description": "Bearer token (CMA authentication)" }
  }
}
```

## Related documents {#related-documents}

- [Content](/api/reference/cma/content.md): The body data where Tags are attached via metadata.tags.
- [Media](/api/reference/cma/media.md): The file resource where Tags are attached via metadata.tags.