Tags

The Tag resource

Tag is a keyword or term associated with a Scalr resource. It is used to label resources across the account to help to identify them, improve searchability or can even participate in a terraform run e.g. as a part of metadata for policy decision.

Tags are unique within the account. Deleted tags will be removed from associated resources.

Key path

Description

type* (string)

Available values: tags

id (string)

attributes.name* (string)

The name of the tag. It must be unique within the account.

relationships.account* (object)

The account this tag belongs to.

relationships.account.data.type* (string)

Available values: accounts

relationships.account.data.id* (string)

links.self (string)

List Tags

GET /api/iacp/v3/tags

This endpoint returns a list of tags.

Query Parameters
  • page[number] (string) – Page number

  • page[size] (string) – Page size

  • filter[account] (string) – The account filter

  • sort (array) – The comma-separated list of attributes. (Available values: name)

  • query (string) – Query string

Example Request:

GET /api/iacp/v3/tags HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK

    Success.

    Example Respone:

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data": [
        {
          "attributes": {
            "name": "staging"
          },
          "id": "tag-u353opfakkha55g",
          "links": {
            "self": "https://my.scalr.io/api/iacp/v3/tags/tag-u353opfakkha55g"
          },
          "relationships": {
            "account": {
              "data": {
                "id": "acc-svrcncgh453bi8g",
                "type": "accounts"
              }
            }
          },
          "type": "tags"
        },
        {
          "attributes": {
            "name": "produciton"
          },
          "id": "tag-u353pbn2l72g6og",
          "links": {
            "self": "https://my.scalr.io/api/iacp/v3/tags/tag-u353pbn2l72g6og"
          },
          "relationships": {
            "account": {
              "data": {
                "id": "acc-svrcncgh453bi8g",
                "type": "accounts"
              }
            }
          },
          "type": "tags"
        }
      ]
    }
    

  • 403 Forbidden – User unauthorized to perform this action.

  • 4XX – Client error.

  • 5XX – Server error.

Create a Tag

POST /api/iacp/v3/tags

Create a new tag in the account.

Request body:

Key path

Description

data.type* (string)

Available values: tags

data.id (string)

data.attributes.name* (string)

The name of the tag. It must be unique within the account.

data.relationships.account* (object)

The account this tag belongs to.

data.relationships.account.data.type* (string)

Available values: accounts

data.relationships.account.data.id* (string)

Example Request:

POST /api/iacp/v3/tags HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
  "data": {
    "type": "tags",
    "attributes": {
      "name": "dev"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "accounts",
          "id": "acc-svrcncgh453bi8g"
        }
      }
    }
  }
}
Status Codes
  • 201 Created

    Successfully created.

    Example Respone:

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data": {
        "attributes": {
          "name": "dev"
        },
        "id": "tag-tsca2n8gob522bg",
        "links": {
          "self": "https://my.scalr.io/api/iacp/v3/tags/tag-tsca2n8gob522bg"
        },
        "relationships": {
          "account": {
            "data": {
              "id": "acc-svrcncgh453bi8g",
              "type": "accounts"
            }
          }
        },
        "type": "tags"
      }
    }
    

  • 403 Forbidden – User unauthorized to perform this action.

  • 404 Not Found – Relationship not found or user unauthorized to perform action.

  • 422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).

  • 4XX – Client error.

  • 5XX – Server error.

Delete a Tag

DELETE /api/iacp/v3/tags/{tag}

The endpoint deletes tag by ID.

Parameters
  • tag (string) – The ID of the tag to delete.

Status Codes

Get a Tag

GET /api/iacp/v3/tags/{tag}

Show details of a specific tag.

Parameters
  • tag (string) – The ID of the tag to show.

Example Request:

GET /api/iacp/v3/tags/{tag} HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK

    Success.

    Example Respone:

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data": {
        "attributes": {
          "name": "dev"
        },
        "id": "tag-tsca2n8gob522bg",
        "links": {
          "self": "https://my.scalr.io/api/iacp/v3/tags/tag-tsca2n8gob522bg"
        },
        "relationships": {
          "account": {
            "data": {
              "id": "acc-svrcncgh453bi8g",
              "type": "accounts"
            }
          }
        },
        "type": "tags"
      }
    }
    

  • 403 Forbidden – User unauthorized to perform this action.

  • 404 Not Found – Relationship not found or user unauthorized to perform action.

  • 4XX – Client error.

  • 5XX – Server error.

Update a Tag

PATCH /api/iacp/v3/tags/{tag}

This endpoint updates tag by ID.

Parameters
  • tag (string) – The ID of the tag to update.

Request body:

Key path

Description

data.type* (string)

Available values: tags

data.id (string)

data.attributes.name* (string)

The name of the tag. It must be unique within the account.

data.relationships.account* (object)

The account this tag belongs to.

data.relationships.account.data.type* (string)

Available values: accounts

data.relationships.account.data.id* (string)

Example Request:

PATCH /api/iacp/v3/tags/{tag} HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
  "data": {
    "type": "tags",
    "id": "tag-tsca2n8gob522bg",
    "attributes": {
      "name": "new-name"
    }
  }
}
Status Codes