Environments

The Environment resource

Environments are collections of related workspaces that correspond to functional areas, SDLC stages, projects or any grouping that is required.

An account can have multiple environments.

Workspaces within an environment are where Terraform configurations are run to deploy infrastructure, and where state files are stored.

An Environment can have set of policy groups assigned that are applied to all workspaces in the environment. The Environment can also have variables, credentials, registry modules, and VCS providers that are available to every workspace.

Key path

Description

type* (string)

Available values: environments

id (string)

attributes.cost-estimation-enabled (boolean)

Indicates if the cost estimation should be performed for runs in the environment.

attributes.created-at (string)

Date/Time the environment was created.

attributes.created-by-email (string)

attributes.name* (string)

The name of the environment.

attributes.permissions (object)

attributes.status (string)

relationships.account* (object)

The account that owns this environment.

relationships.account.data.type* (string)

Available values: accounts

relationships.account.data.id* (string)

relationships.cloud-credentials (object)

The attribute cloud-credentials is deprecated. Use default-provider-configurations instead.

relationships.cloud-credentials.data* (array)

relationships.created-by (object)

The user that created the environment.

relationships.created-by.data.type* (string)

Available values: users

relationships.created-by.data.id* (string)

relationships.default-provider-configurations (object)

Provider configurations used in the environment workspaces by default.

relationships.default-provider-configurations.data* (array)

relationships.policy-groups.data* (array)

relationships.provider-configurations (object)

Provider configurations available for this environment.

relationships.provider-configurations.data* (array)

relationships.tags.data* (array)

links.self (string)

List Environments

GET /environments

This endpoint lists account environments.

Query Parameters

  • filter[account] (string) – The ID of the Account

  • filter[environment] (string) – The ID of the Environment

  • filter[latest-run-date] (string) – Filter by latest run date. Example: filter[latest-run-date]=between:2022-01-01T00:00:00Z,2022-02-01T00:00:00Z

  • filter[policy-group] (string) – The ID of the Policy Group.

  • page[number] (string) – Page number

  • page[size] (string) – Page size

  • query (string) – Query string, search by id, name.

  • filter[tag] (string) – Filter environments by tags

  • sort (array) – The comma-separated list of attributes. (Available values: account, cost-estimation-enabled, created-at, created-by-email, name)

  • include (array) – The comma-separated list of relationship paths. (Available values: account, cloud-credentials, created-by, default-provider-configurations, policy-groups, provider-configurations, tags)

  • fields (object) – The value of any fields[resource-type] parameter is a comma-separated list that refers to the name of the fields to be returned for resource. The comma-separated field names fields to be returned for resource. An empty value indicates that no fields should be returned.

Example Request:

GET /environments 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": {
        "cost-estimation-enabled": true,
        "created-at": "2019-07-17T16:26:05Z",
        "name": "dev",
        "status": "Active"
      },
      "id": "env-sfuari395m7sck1",
      "links": {
        "self": "https://my.scalr.io/api/iacp/v3/environments/env-sfuari395m7sck1"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "acc-t2fcrq6h1v3nf0g",
            "type": "accounts"
          }
        },
        "created-by": {
          "data": {
            "id": "user-t45rlmfnqtqvhh8",
            "type": "users"
          }
        }
      },
      "type": "environments"
    },
    {
      "attributes": {
        "cost-estimation-enabled": true,
        "created-at": "2019-12-03T08:34:56Z",
        "name": "prod",
        "status": "Active"
      },
      "id": "env-skvcvdb6odtbbd0",
      "links": {
        "self": "https://my.scalr.io/api/iacp/v3/environments/env-skvcvdb6odtbbd0"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "acc-t2fcrq6h1v3nf0g",
            "type": "accounts"
          }
        },
        "created-by": {
          "data": {
            "id": "user-stp8qjcvjljlo1o",
            "type": "users"
          }
        },
      },
      "type": "environments"
    }
  ],
  "included": null,
  "links": {
    "first": "https://my.scalr.io/api/iacp/v3/environments?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "last": "https://my.scalr.io/api/iacp/v3/environments?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "next": null,
    "prev": null,
    "self": "https://my.scalr.io/api/iacp/v3/environments?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "next-page": null,
      "prev-page": null,
      "total-count": 2,
      "total-pages": 1
    }
  }
}

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

  • 4XX – Client error.

  • 5XX – Server error.

Request Headers

  • Prefer – Specifies the API profile that server should use to handle this request. For the list of supported profiles check out the Scalr documentation. (Required)

Create an Environment

POST /environments

Create a new environment in the account.

Query Parameters

  • fields (object) – The value of any fields[resource-type] parameter is a comma-separated list that refers to the name of the fields to be returned for resource. The comma-separated field names fields to be returned for resource. An empty value indicates that no fields should be returned.

Request body:

Key path

Description

data.type* (string)

Available values: environments

data.attributes.cost-estimation-enabled (boolean)

Indicates if the cost estimation should be performed for runs in the environment.

data.attributes.name* (string)

The name of the environment.

data.relationships.account* (object)

The account that owns this environment.

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

Available values: accounts

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

data.relationships.cloud-credentials (object)

The attribute cloud-credentials is deprecated. Use default-provider-configurations instead.

data.relationships.cloud-credentials.data* (array)

data.relationships.default-provider-configurations (object)

Provider configurations used in the environment workspaces by default.

data.relationships.default-provider-configurations.data* (array)

data.relationships.policy-groups.data* (array)

data.relationships.tags.data* (array)

Example Request:

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

{
  "data": {
    "type": "environments",
    "attributes": {
      "name": "staging"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "acc-t2fcrq6h1v3nf0g",
          "type": "accounts"
        }
      }
    }
  }
}

Create an environment with tags:

To create an environment with tags, the Tag resources should be created first in the account. Then Tags can be passed as relationship objects in create environment payload.

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

{
  "data": {
    "type": "environments",
    "attributes": {
      "name": "staging"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "acc-t2fcrq6h1v3nf0g",
          "type": "accounts"
        }
      },
      "tags": {
        "data": [
          {
            "id": "tag-xxx",
            "type": "tags"
          },
          {
            "id": "tag-yyy",
            "type": "tags"
          }
        ]
      }
    }
  }
}
Status Codes

  • 201 Created –

    The environment was created.

    Example Respone:

    HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
Preference-Applied: profile=preview

{
  "data": {
    "attributes": {
      "cost-estimation-enabled": true,
      "created-at": "2020-11-05T05:11:21Z",
      "name": "staging",
      "status": "Active"
    },
    "id": "env-t5v458aus4r7fc8",
    "links": {
      "self": "https://my.scalr.io/api/iacp/v3/environments/env-t5v458aus4r7fc8"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "acc-t2fcrq6h1v3nf0g",
          "type": "accounts"
        }
      },
      "created-by": {
        "data": {
          "id": "user-stp8qjcvjljlo1o",
          "type": "users"
        }
      },
    },
    "type": "environments"
  },
  "included": null,
  "meta": null
}

  • 404 Not Found – Account relationship not found, or user unauthorized to perform action.

  • 422 Unprocessable Entity – Invalid arguments.

  • 4XX – Client error.

  • 5XX – Server error.

Request Headers

  • Prefer – Specifies the API profile that server should use to handle this request. For the list of supported profiles check out the Scalr documentation. (Required)

Delete an Environment

DELETE /environments/{environment}
Parameters

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

Status Codes

  • 204 No Content – Successfully deleted the environment.

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

  • 4XX – Client error.

  • 5XX – Server error.

Request Headers

  • Prefer – Specifies the API profile that server should use to handle this request. For the list of supported profiles check out the Scalr documentation. (Required)

Get an Environment

GET /environments/{environment}

Show details of a specific environment.

Parameters

  • environment (string) – The ID of the environment.

Query Parameters

  • include (array) – The comma-separated list of relationship paths. (Available values: account, cloud-credentials, created-by, default-provider-configurations, policy-groups, provider-configurations, tags)

  • fields (object) – The value of any fields[resource-type] parameter is a comma-separated list that refers to the name of the fields to be returned for resource. The comma-separated field names fields to be returned for resource. An empty value indicates that no fields should be returned.

Example Request:

GET /environments/{environment} 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": {
      "cost-estimation-enabled": true,
      "created-at": "2019-07-17T16:26:05Z",
      "name": "dev",
      "status": "Active"
    },
    "id": "env-sfuari395m7sck1",
    "links": {
      "self": "https://my.scalr.io/api/iacp/v3/environments/env-sfuari395m7sck1"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "acc-t2fcrq6h1v3nf0g",
          "type": "accounts"
        }
      },
      "created-by": {
        "data": {
          "id": "user-t45rlmfnqtqvhh8",
          "type": "users"
        }
      },
    },
    "type": "environments"
  },
  "included": null,
  "meta": null
}

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

  • 4XX – Client error.

  • 5XX – Server error.

Request Headers

  • Prefer – Specifies the API profile that server should use to handle this request. For the list of supported profiles check out the Scalr documentation. (Required)

Update Environment

PATCH /environments/{environment}
Parameters

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

Query Parameters

  • fields (object) – The value of any fields[resource-type] parameter is a comma-separated list that refers to the name of the fields to be returned for resource. The comma-separated field names fields to be returned for resource. An empty value indicates that no fields should be returned.

Request body:

Key path

Description

data.type* (string)

Available values: environments

data.attributes.cost-estimation-enabled (boolean)

Indicates if the cost estimation should be performed for runs in the environment.

data.attributes.name* (string)

The name of the environment.

data.relationships.account* (object)

The account that owns this environment.

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

Available values: accounts

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

data.relationships.cloud-credentials (object)

The attribute cloud-credentials is deprecated. Use default-provider-configurations instead.

data.relationships.cloud-credentials.data* (array)

data.relationships.default-provider-configurations (object)

Provider configurations used in the environment workspaces by default.

data.relationships.default-provider-configurations.data* (array)

data.relationships.policy-groups.data* (array)

data.relationships.tags.data* (array)

Rename the environment:

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

{
  "data": {
    "type": "environments",
    "id": "env-t5v458aus4r7fc8",
    "attributes": {
      "name": "new-name"
    }
  }
}

Link policy groups to the environment:

The Policy groups list provided in the request will override the existing policy groups. If you are adding more groups, ensure that you include the existing groups as well.

This works the same for cloud credentials.

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

{
  "data": {
    "relationships": {
      "policy-groups": {
        "data": [
          {
            "id": "pgrp-svsu2dqfvtk5qfg",
            "type": "policy-groups"
          },
          {
            "id": "pgrp-tmttm6aiq13a6bo",
            "type": "policy-groups"
          }
        ]
      }
    },
    "type": "environments"
  }
}
Status Codes

  • 200 OK –

    Successfully updated the environment.

    Example Respone:

    HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Preference-Applied: profile=preview

{
  "data": {
    "attributes": {
      "cost-estimation-enabled": true,
      "created-at": "2020-11-05T05:11:21Z",
      "name": "new-name",
      "status": "Active"
    },
    "id": "env-t5v458aus4r7fc8",
    "links": {
      "self": "https://my.scalr.io/api/iacp/v3/environments/env-t5v458aus4r7fc8"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "acc-t2fcrq6h1v3nf0g",
          "type": "accounts"
        }
      },
      "created-by": {
        "data": {
          "id": "user-stp8qjcvjljlo1o",
          "type": "users"
        }
      },
    },
    "type": "environments"
  },
  "included": null,
  "meta": null
}

  • 404 Not Found – Environment or relationship not found, or user unauthorized to perform action.

  • 422 Unprocessable Entity – Invalid arguments.

  • 4XX – Client error.

  • 5XX – Server error.

Request Headers

  • Prefer – Specifies the API profile that server should use to handle this request. For the list of supported profiles check out the Scalr documentation. (Required)

Delete environment’s tags

DELETE /environments/{environment}/relationships/tags

This endpoint removes given tags from the environment.

Parameters

  • environment (string) – The environment whose tags will be deleted.

Request body:

Key path

Description

data (array)

Example Request:

The body must contain a data member whose value is an empty array or an array of tag identifier objects.

DELETE /environments/{environment}/relationships/tags HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
  "data": [
    {
      "type": "tags",
      "id": "tag-ttiuc2l4mdd5lf8"
    },
    {
      "type": "tags",
      "id": "tag-ttk084u5h8cajb0"
    }
  ]
}
Status Codes
Request Headers

  • Prefer – Specifies the API profile that server should use to handle this request. For the list of supported profiles check out the Scalr documentation. (Required)

List environment’s tags

GET /environments/{environment}/relationships/tags

This endpoint returns a list of tags, assigned to an environment.

Parameters

  • environment (string) – The environment to list tags for.

Query Parameters

  • page[number] (string) – Page number

  • page[size] (string) – Page size

Example Request:

GET /environments/{environment}/relationships/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": [
    {
      "id": "tag-u81anm0gc39ofco",
      "type": "tags"
    },
    {
      "id": "tag-u81anm0ifn8jm5g",
      "type": "tags"
    }
  ],
  "links": {
    "self": "https://my.scalr.io/api/iacp/v3/environments/env-e83a5c529096sao/relationships/tags"
  }
}

  • 403 Forbidden – User unauthorized to perform this action.

  • 4XX – Client error.

  • 5XX – Server error.

Request Headers

  • Prefer – Specifies the API profile that server should use to handle this request. For the list of supported profiles check out the Scalr documentation. (Required)

Replace environment’s tags

PATCH /environments/{environment}/relationships/tags

This endpoint completely replaces environment’s tags with provided list.

Parameters

  • environment (string) – The environment whose tags will be replaced.

Request body:

Key path

Description

data (array)

Example Request:

The body must contain a data member whose value is an empty array or an array of tag identifier objects.

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

{
  "data": [
    {
      "type": "tags",
      "id": "tag-ttiuc2l4mdd5lf8"
    },
    {
      "type": "tags",
      "id": "tag-ttk084u5h8cajb0"
    }
  ]
}

Clear all tags for a resource:

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

{
  "data": []
}
Status Codes
Request Headers

  • Prefer – Specifies the API profile that server should use to handle this request. For the list of supported profiles check out the Scalr documentation. (Required)

Add tags to the environment

POST /environments/{environment}/relationships/tags

This endpoint assigns the list of tags to the environment.

Parameters

  • environment (string) – The environment to add the tags to.

Request body:

Key path

Description

data (array)

Example Request:

The body must contain a data member whose value is an empty array or an array of tag identifier objects.

POST /environments/{environment}/relationships/tags HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
  "data": [
    {
      "type": "tags",
      "id": "tag-ttiuc2l4mdd5lf8"
    },
    {
      "type": "tags",
      "id": "tag-ttk084u5h8cajb0"
    }
  ]
}
Status Codes
Request Headers

  • Prefer – Specifies the API profile that server should use to handle this request. For the list of supported profiles check out the Scalr documentation. (Required)