--- title: "Create tag group" method: POST path: "/api/v1/tag-groups" tags: ["Tag Groups"] --- # Create tag group `POST /api/v1/tag-groups` ## Request - Base URL: `https://app.scanopy.net` - URL: `https://app.scanopy.net/api/v1/tag-groups` - Auth: one of: - API key in header `Authorization` - API key in cookie `session_id` Creates a group your organization names. Group names are unique within the organization, and "Application" and "Status" are reserved for the system groups. ## Request body - TagGroup: A named set of tags of which an entity holds at most one, in an order the organization sets, optionally limited to some entity types. - `description` string, nullable, required: What the group is for. - `entity_types` EntityDiscriminants[], nullable, required: The entity types this group's tags can be applied to. `null` allows every taggable type the group type admits: Status leaves out types that carry a status of their own. Fixed for Visibility, which applies to hosts. - `group_type` 'Application' | 'Status' | 'Visibility' | 'Custom', required: What kind of tag group this is. `Application`, `Status` and `Visibility` are system groups: every organization has exactly one of each, and they can't be renamed, deleted or recreated. Application tags drive the application view. Status tags track where an asset is on its way from planned to decommissioned, on entities that have no status of their own. A host holding a Visibility tag is left out of topology. `Custom` groups are named by the organization. - `name` string, required: The group's name. A system group's name is fixed. - `ordered` boolean, required: Whether the group's tags have an order the organization sets. An unordered group lists its tags by name. Fixed for system groups: statuses are ordered, applications are not. - `organization_id` string, uuid, required: The organization that owns this record. - `scope_computed` boolean, required: Whether `entity_types` is computed from entity metadata (Status, Visibility) rather than set by the organization. A computed scope is read-only and never stored. - `created_at` string, date-time, required: When this record was first created. - `id` string, uuid, required: Server-assigned unique identifier. - `updated_at` string, date-time, required: When this record was last modified. ## Response `200` Tag group created - ApiResponseTagGroup: Envelope for a successful response. Failures are sent with a non-2xx status and an `ApiErrorResponse` body instead. - `data` object: A named set of tags of which an entity holds at most one, in an order the organization sets, optionally limited to some entity types. - `description` string, nullable, required: What the group is for. - `entity_types` EntityDiscriminants[], nullable, required: The entity types this group's tags can be applied to. `null` allows every taggable type the group type admits: Status leaves out types that carry a status of their own. Fixed for Visibility, which applies to hosts. - `group_type` 'Application' | 'Status' | 'Visibility' | 'Custom', required: What kind of tag group this is. `Application`, `Status` and `Visibility` are system groups: every organization has exactly one of each, and they can't be renamed, deleted or recreated. Application tags drive the application view. Status tags track where an asset is on its way from planned to decommissioned, on entities that have no status of their own. A host holding a Visibility tag is left out of topology. `Custom` groups are named by the organization. - `name` string, required: The group's name. A system group's name is fixed. - `ordered` boolean, required: Whether the group's tags have an order the organization sets. An unordered group lists its tags by name. Fixed for system groups: statuses are ordered, applications are not. - `organization_id` string, uuid, required: The organization that owns this record. - `scope_computed` boolean, required: Whether `entity_types` is computed from entity metadata (Status, Visibility) rather than set by the organization. A computed scope is read-only and never stored. - `created_at` string, date-time, required: When this record was first created. - `id` string, uuid, required: Server-assigned unique identifier. - `updated_at` string, date-time, required: When this record was last modified. - `error` string, nullable: Not sent on a successful response. Failure messages arrive in an `ApiErrorResponse`. - `meta` ApiMeta, required: API metadata included in all responses - `api_version` integer, required: API version (integer, increments on breaking changes) - `server_version` string, required: Server version (semver) - `success` boolean, required: Always `true` on a successful response. ## Other responses - `400`: Validation error ## Changes - **2026-10-23** `9dda1a8b8ed1`: 2 info - the request required property `allOf[#/components/schemas/TagGroupBase]/group_type` became read-only - the response required property `data/allOf[#/components/schemas/TagGroupBase]/group_type` became read-only for the status `200` - **2026-10-11** `e5d9c243ed3c`: 1 breaking, 1 warning, 3 info - added the new required request property `allOf[#/components/schemas/TagGroupBase]/description` - added the new `Visibility` enum value to the `data/allOf[#/components/schemas/TagGroupBase]/group_type` response property for the response status `200` - added the new `Visibility` enum value to the request property `allOf[#/components/schemas/TagGroupBase]/group_type` - added the required property `data/allOf[#/components/schemas/TagGroupBase]/description` to the response with the `200` status - …1 more - **2026-10-11** `8de5826e9ffc`: 1 breaking, 1 info - added the new required request property `allOf[#/components/schemas/TagGroupBase]/ordered` - added the required property `data/allOf[#/components/schemas/TagGroupBase]/ordered` to the response with the `200` status - **2026-10-11** `fb5e0436b49e`: 1 info - endpoint added [Operation history](https://skmtc.dev/scanopy/apis/scanopy-api/changes/api/v1/tag-groups/post.md) --- [API](https://skmtc.dev/scanopy/apis/scanopy-api.md) - [All operations](https://skmtc.dev/scanopy/apis/scanopy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/scanopy/apis/scanopy-api/revisions/966ba786bdb5?raw)