UpCloud

Tags

Tags provide a way to group and categorize servers. Each tag has a unique name and optional description. Servers can have multiple tags, and tags can be assigned to multiple servers.

Tags are useful for organizing servers by environment (production, staging, development), role (web, database, cache), or any other classification that fits your workflow.

GET/1.3/tag

List tags

Returns all existing tags with their properties and the servers assigned to each tag.

Response fields

  • Name
    name
    Type
    string
    Description

    Tag name (1-32 characters, alphanumeric and underscore).

  • Name
    description
    Type
    string
    Description

    Tag description (max 255 characters).

  • Name
    servers
    Type
    object
    Description

    List of server UUIDs assigned to this tag.

Request

GET
/1.3/tag
curl -X GET https://api.upcloud.com/1.3/tag \
  -u your_username:your_password
POST/1.3/tag

Create tag

Creates a new tag. Existing servers can be tagged in the same request.

Attributes

  • Name
    name
    Type
    string
    Description

    Tag name (1-32 characters: A-Z, a-z, 0-9, underscore). Required.

  • Name
    description
    Type
    string
    Description

    Tag description (max 255 characters).

  • Name
    servers
    Type
    object
    Description

    List of server UUIDs to assign to the tag.

Request

POST
/1.3/tag
curl -X POST https://api.upcloud.com/1.3/tag \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "DEV",
      "description": "Development servers",
      "servers": {
        "server": [
          "0077fa3d-32db-4b09-9f5f-30d9e9afb565"
        ]
      }
    }
  }'
PUT/1.3/tag/{tagname}

Modify tag

Modifies an existing tag. You can rename the tag, change its description, or update the list of assigned servers.

Attributes

  • Name
    name
    Type
    string
    Description

    New tag name (to rename the tag).

  • Name
    description
    Type
    string
    Description

    Updated description.

  • Name
    servers
    Type
    object
    Description

    Updated list of server UUIDs.

Request

PUT
/1.3/tag/{tagname}
curl -X PUT https://api.upcloud.com/1.3/tag/DEV \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "PROD",
      "description": "Production servers",
      "servers": {
        "server": [
          "0077fa3d-32db-4b09-9f5f-30d9e9afb565"
        ]
      }
    }
  }'
DELETE/1.3/tag/{tagname}

Delete tag

Deletes an existing tag. This untags all servers from the specified tag and deletes the tag definition.

Request

DELETE
/1.3/tag/{tagname}
curl -X DELETE https://api.upcloud.com/1.3/tag/DEV \
  -u your_username:your_password
POST/1.3/server/{uuid}/tag/{tags}

Assign tag to server

Assigns one or more tags to a server. The tags must already exist.

The tags parameter is a comma-separated list of tag names to assign.

Request

POST
/1.3/server/{uuid}/tag/{tags}
curl -X POST https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/tag/DEV,web \
  -u your_username:your_password
POST/1.3/server/{uuid}/untag/{tags}

Remove tag from server

Removes one or more tags from a server. The tags must exist.

The tags parameter is a comma-separated list of tag names to remove.

Request

POST
/1.3/server/{uuid}/untag/{tags}
curl -X POST https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/untag/DEV \
  -u your_username:your_password