---
updatedAt: 2026-05-28T08:16:45.000Z
agentTools:
  projectIndex: https://docs.scalr.io/llms.txt
---

# Create a Tag

Create a new tag in the account.


# OpenAPI definition

```json
{
  "components": {
    "schemas": {
      "Tag": {
        "description": "Tag is a keyword or term associated with a Scalr resource.\nIt is used to label resources across the account to help to identify them, improve searchability\nor can even participate in a terraform run e.g. as a part of metadata for policy decision.\n\nTags are unique within the account. Deleted tags will be removed from associated resources.\n\nThe extra fields below are not available in response by default. Ask for them explicitly in the query parameter `fields[tags]`:\n* in-use",
        "properties": {
          "attributes": {
            "properties": {
              "in-use": {
                "description": "Whether the tag is used by any resource.",
                "nullable": true,
                "readOnly": true,
                "type": "boolean"
              },
              "name": {
                "description": "The name of the tag. It must be unique within the account.",
                "maxLength": 255,
                "type": "string"
              }
            },
            "required": [
              "name"
            ],
            "type": "object"
          },
          "id": {
            "readOnly": true,
            "type": "string"
          },
          "links": {
            "properties": {
              "self": {
                "readOnly": true,
                "type": "string"
              }
            },
            "readOnly": true,
            "type": "object"
          },
          "relationships": {
            "properties": {
              "account": {
                "description": "The account this tag belongs to.",
                "properties": {
                  "data": {
                    "nullable": true,
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "type": {
                        "enum": [
                          "accounts",
                          ""
                        ],
                        "type": "string"
                      }
                    },
                    "required": [
                      "type",
                      "id"
                    ],
                    "type": "object"
                  }
                },
                "readOnly": true,
                "required": [
                  "data"
                ],
                "type": "object"
              }
            },
            "type": "object"
          },
          "type": {
            "enum": [
              "tags"
            ],
            "type": "string"
          }
        },
        "required": [
          "type",
          "attributes"
        ],
        "type": "object"
      },
      "TagDocument": {
        "description": "JSON:API Document.\n\nsee: https://jsonapi.org/format/#document-structure",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Tag"
          },
          "included": {
            "items": {
              "type": "object"
            },
            "readOnly": true,
            "type": "array"
          },
          "meta": {
            "readOnly": true,
            "type": "object"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "API-Key": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Scalr IACP API",
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0"
    },
    "title": "Scalr IACP API",
    "version": "unversioned"
  },
  "openapi": "3.0.0",
  "paths": {
    "/tags": {
      "post": {
        "description": "Create a new tag in the account.\n",
        "operationId": "create_tag",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/vnd.api+json": {
              "examples": {
                "default": {
                  "value": "{\n  \"data\": {\n    \"type\": \"tags\",\n    \"attributes\": {\n      \"name\": \"dev\"\n    },\n    \"relationships\": {\n      \"account\": {\n        \"data\": {\n          \"type\": \"accounts\",\n          \"id\": \"acc-svrcncgh453bi8g\"\n        }\n      }\n    }\n  }\n}"
                }
              },
              "schema": {
                "$ref": "#/components/schemas/TagDocument"
              }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/vnd.api+json": {
                "examples": {
                  "default": {
                    "value": "{\n  \"data\": {\n    \"attributes\": {\n      \"name\": \"dev\"\n    },\n    \"id\": \"tag-tsca2n8gob522bg\",\n    \"links\": {\n      \"self\": \"https://my.scalr.io/api/iacp/v3/tags/tag-tsca2n8gob522bg\"\n    },\n    \"relationships\": {\n      \"account\": {\n        \"data\": {\n          \"id\": \"acc-svrcncgh453bi8g\",\n          \"type\": \"accounts\"\n        }\n      }\n    },\n    \"type\": \"tags\"\n  }\n}"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/TagDocument"
                }
              }
            },
            "description": "Successfully created."
          },
          "403": {
            "description": "User unauthorized to perform this action."
          },
          "404": {
            "description": "Relationship not found or user unauthorized to perform action."
          },
          "422": {
            "description": "Malformed request body (missing attributes, wrong types, etc.)."
          },
          "4XX": {
            "description": "Client error."
          },
          "5XX": {
            "description": "Server error."
          }
        },
        "summary": "Create a Tag",
        "tags": [
          "tags"
        ],
        "x-resource": "Tag",
        "x-service": "tf-api"
      }
    }
  },
  "security": [
    {
      "API-Key": []
    }
  ],
  "servers": [
    {
      "url": "https://{Domain}/api/iacp/v3",
      "variables": {
        "Domain": {
          "default": "example.scalr.io",
          "description": "Domain where Scalr is hosted"
        }
      }
    }
  ]
}
```

# Sibling pages

* [List Tags](https://docs.scalr.io/scalr/reference/list_tags.md)
* [Delete a Tag](https://docs.scalr.io/scalr/reference/delete_tag.md)
* [Get a Tag](https://docs.scalr.io/scalr/reference/get_tag.md)
* [Update a Tag](https://docs.scalr.io/scalr/reference/update_tag.md)