Workspaces

The Workspace resource

A Workspace is where Terraform runs are performed for a specific configuration, and where the resulting state file(s) are stored.

Workspaces belong to environments and can have variables configured to provide inputs to the configuration, authenticate providers etc.

Key path

Description

type* (string)

Available values: workspaces

id (string)

attributes.apply-schedule (string)

Cron expression for scheduled runs. Time should be in UTC.

attributes.auto-apply (boolean)

Indicates whether terraform apply should automatically run when terraform plan ends without error. Default false.

attributes.auto-queue-runs (object)

Available values: always, never, skip_first

Indicates if runs have to be queued automatically when a new configuration version is uploaded. skip_first - after the very first configuration version is uploaded into the workspace the run will not be triggered.

But the following configurations will do. This is the default behavior.

always - runs will be triggered automatically on every upload of the configuration version. never - configuration versions are uploaded into the workspace, but runs will not be triggered.

attributes.created-at (string)

The resource creation timestamp.

attributes.destroy-schedule (string)

Cron expression for scheduled destroy runs. Time should be in UTC.

attributes.execution-mode (string)

Available values: remote, local

Which execution mode to use. Valid values are remote and local. When set to local, the workspace will be used for state storage only.

attributes.force-latest-run (boolean)

Indicates whether force run should automatically apply to latest run. Default false.

attributes.global-remote-state (boolean)

Specifies if the state is globally shared within the environment.

attributes.has-resources (boolean)

Indicates whether the workspace’s current state version contains terraform resources.

attributes.hooks.post-apply (string)

Command that should be run after terraform apply operation executed.

attributes.hooks.post-plan (string)

Command that should be run after terraform plan operation executed.

attributes.hooks.pre-apply (string)

Command that should be run before terraform apply operation executed.

attributes.hooks.pre-init (string)

Command that should be run before terraform init operation executed.

attributes.hooks.pre-plan (string)

Command that should be run before terraform plan operation executed.

attributes.lock-reason (string)

The reason (if any) that the workspace has been locked.

attributes.locked (boolean)

Indicates whether the workspace is locked for operations. The lock-reason attribute carries the explanation.

This semaphore is acquired and released by terraform apply and can also manage it with Lock/Unlock Workspace.

Default: false

attributes.name* (string)

Workspace name which must be unique within the environment.

Comprises letters, numbers, -, and _ only.

attributes.operations (boolean)

The attribute operations is deprecated. Use execution-mode instead.

attributes.permissions (object)

attributes.run-operation-timeout (integer)

The timeout for the Terraform Run operations (in minutes).

attributes.terraform-version (string)

The version of Terraform the workspace performs runs on. If omitted, the system default version is assigned.

attributes.updated-at (string)

The resource last update timestamp.

attributes.updated-by-email (string)

The email of the last user, that updated this workspace.

attributes.var-files (array)

attributes.vcs-repo.branch (string)

Branch of a repository the workspace is associated with. If omitted, the repository default branch will be used.

attributes.vcs-repo.dry-runs-enabled (boolean)

When true once a pull request into the vcs-repo.branch is opened, every push to a pull request’s branch will trigger a dry run in the workspace. Default true

attributes.vcs-repo.identifier* (string)

A reference to your VCS repository.

For GitHub, GitHub Enterprise and GitLab the format is <org>/<repo>. Azure DevOps Services has the format <org>/<project>/<repo>.

attributes.vcs-repo.ingress-submodules (boolean)

Specifies whether git submodules should be fetched when cloning the VCS repository.

attributes.vcs-repo.path (string)

The attribute vcs-repo.path is deprecated. Use working-directory and trigger-prefixes instead.

attributes.vcs-repo.trigger-prefixes (array)

List of paths (relative to the configuration version root), whose changes will trigger a run for the workspace using this binding when the CV is created. If omitted, any change in he configuration version root will trigger a new run.

attributes.working-directory (string)

A relative path where Terraform commands will execute in.

relationships.agent-pool (object)

The ID of the agent pool.

relationships.agent-pool.data.type* (string)

Available values: agent-pools

relationships.agent-pool.data.id* (string)

relationships.configuration-version (object)

The latest uploaded configuration version.

relationships.configuration-version.data.type* (string)

Available values: configuration-versions

relationships.configuration-version.data.id* (string)

relationships.created-by (object)

The user, who has triggered the run.

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

Available values: users

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

relationships.current-run (object)

Currently executing Run.

relationships.current-run.data.type* (string)

Available values: runs

relationships.current-run.data.id* (string)

relationships.environment (object)

The environment this workspace belongs to.

relationships.environment.data.type* (string)

Available values: environments

relationships.environment.data.id* (string)

relationships.latest-configuration-version (object)

The configuration version of the latest non-dry Run in this workspace.

relationships.latest-configuration-version.data.type* (string)

Available values: configuration-versions

relationships.latest-configuration-version.data.id* (string)

relationships.latest-run (object)

Latest finished Run.

relationships.latest-run.data.type* (string)

Available values: runs

relationships.latest-run.data.id* (string)

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

Available values: users

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

relationships.locked-by-run.data.type* (string)

Available values: runs

relationships.locked-by-run.data.id* (string)

relationships.module-version (object)

The ID of the module version.

relationships.module-version.data.type* (string)

Available values: module-versions

relationships.module-version.data.id* (string)

relationships.tags.data* (array)

relationships.updated-by (object)

The last user, that updated this workspace.

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

Available values: users

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

relationships.vcs-provider (object)

VCS provider of the Run’s workspace

relationships.vcs-provider.data.type* (string)

Available values: vcs-providers

relationships.vcs-provider.data.id* (string)

links.self (string)

List Workspaces

GET /workspaces
Query Parameters
  • filter[environment] (string) – The ID of the Environment

  • filter[workspace] (string) – The ID(s) of the Workspace.

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

  • filter[created-by] (string) – The ID of the User who created this workspace

  • filter[name] (string) – Workspace name

  • filter[run][status] (string) – Last run status

  • filter[run][created-by] (string) – Last run created by filter

  • filter[agent-pool] (string) – The ID(s) of the Agent Pool.

  • filter[software-version] (string) – The ID of the Software Version

  • filter[provider-configuration] (string) – The ID of the Provider configuration.

  • page[number] (string) – Page number

  • page[size] (string) – Page size

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

  • filter[updated-at] (string) – Date of workspace modification.

  • filter[updated-by] (string) – The ID of the User who update this workspace

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

  • include (array) – The comma-separated list of relationship paths. (Available values: agent-pool, configuration-version, created-by, environment, latest-configuration-version, latest-run, locked-by, locked-by-run, module-version, tags, updated-by, vcs-provider)

  • sort (array) – The comma-separated list of attributes. (Available values: environment, latest-run, name, updated-at)

Example Request:

GET /workspaces HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK – Success.

  • 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)

Create a Workspace

POST /workspaces

Workspaces represent a unit of infrastructure managed by terraform.

To create a workspace you must pass name attribute and environment relationship.

A workspace might be linked to a VCS repository, so that any git push will trigger a terraform Run in the workspace.

Request body:

Key path

Description

data.type* (string)

Available values: workspaces

data.attributes.auto-apply (boolean)

Indicates whether terraform apply should automatically run when terraform plan ends without error. Default false.

data.attributes.auto-queue-runs (object)

Available values: always, never, skip_first

Indicates if runs have to be queued automatically when a new configuration version is uploaded. skip_first - after the very first configuration version is uploaded into the workspace the run will not be triggered.

But the following configurations will do. This is the default behavior.

always - runs will be triggered automatically on every upload of the configuration version. never - configuration versions are uploaded into the workspace, but runs will not be triggered.

data.attributes.execution-mode (string)

Available values: remote, local

Which execution mode to use. Valid values are remote and local. When set to local, the workspace will be used for state storage only.

data.attributes.force-latest-run (boolean)

Indicates whether force run should automatically apply to latest run. Default false.

data.attributes.global-remote-state (boolean)

Specifies if the state is globally shared within the environment.

data.attributes.hooks.post-apply (string)

Command that should be run after terraform apply operation executed.

data.attributes.hooks.post-plan (string)

Command that should be run after terraform plan operation executed.

data.attributes.hooks.pre-apply (string)

Command that should be run before terraform apply operation executed.

data.attributes.hooks.pre-init (string)

Command that should be run before terraform init operation executed.

data.attributes.hooks.pre-plan (string)

Command that should be run before terraform plan operation executed.

data.attributes.name* (string)

Workspace name which must be unique within the environment.

Comprises letters, numbers, -, and _ only.

data.attributes.operations (boolean)

The attribute operations is deprecated. Use execution-mode instead.

data.attributes.run-operation-timeout (integer)

The timeout for the Terraform Run operations (in minutes).

data.attributes.terraform-version (string)

The version of Terraform the workspace performs runs on. If omitted, the system default version is assigned.

data.attributes.var-files (array)

data.attributes.vcs-repo.branch (string)

Branch of a repository the workspace is associated with. If omitted, the repository default branch will be used.

data.attributes.vcs-repo.dry-runs-enabled (boolean)

When true once a pull request into the vcs-repo.branch is opened, every push to a pull request’s branch will trigger a dry run in the workspace. Default true

data.attributes.vcs-repo.identifier* (string)

A reference to your VCS repository.

For GitHub, GitHub Enterprise and GitLab the format is <org>/<repo>. Azure DevOps Services has the format <org>/<project>/<repo>.

data.attributes.vcs-repo.ingress-submodules (boolean)

Specifies whether git submodules should be fetched when cloning the VCS repository.

data.attributes.vcs-repo.path (string)

The attribute vcs-repo.path is deprecated. Use working-directory and trigger-prefixes instead.

data.attributes.vcs-repo.trigger-prefixes (array)

List of paths (relative to the configuration version root), whose changes will trigger a run for the workspace using this binding when the CV is created. If omitted, any change in he configuration version root will trigger a new run.

data.attributes.working-directory (string)

A relative path where Terraform commands will execute in.

data.relationships.agent-pool (object)

The ID of the agent pool.

data.relationships.agent-pool.data.type* (string)

Available values: agent-pools

data.relationships.agent-pool.data.id* (string)

data.relationships.environment (object)

The environment this workspace belongs to.

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

Available values: environments

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

data.relationships.module-version (object)

The ID of the module version.

data.relationships.module-version.data.type* (string)

Available values: module-versions

data.relationships.module-version.data.id* (string)

data.relationships.tags.data* (array)

data.relationships.vcs-provider (object)

VCS provider of the Run’s workspace

data.relationships.vcs-provider.data.type* (string)

Available values: vcs-providers

data.relationships.vcs-provider.data.id* (string)

Create a workspace with tags:

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

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

{
  "data": {
    "type": "workspaces",
    "attributes": {
      "name": "my-workspace"
    },
    "relationships": {
      "environment": {
        "data": {
          "id": "env-xxx",
          "type": "environments"
        }
      },
      "tags": {
        "data": [
          {
            "id": "tag-xxx",
            "type": "tags"
          },
          {
            "id": "tag-yyy",
            "type": "tags"
          }
        ]
      }
    },

  }
}

Create workspace bound to a GitHub repository:

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

{
  "data": {
    "type": "workspaces",
    "attributes": {
      "name": "vcs-bounded",
      "vcs-repo": {
        "identifier": "MyOrg/infra-monorepo",
        "branch": "master"
      },
      "working-directory": "gke-cluster-with-cloudsql"
    },
    "relationships": {
      "environment": {
        "data": {
          "type": "environments",
          "id": "env-sfuari395m7sck1"
        }
      },
      "vcs-provider": {
        "data": {
          "type": "vcs-providers",
          "id": "vcs-stj8n4dj13oevh8"
        }
      }
    }
  }
}

Create workspace without VCS:

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

{
  "data": {
    "type": "workspaces",
    "attributes": {
      "name": "vcs-less",
      "auto-apply": true
    },
    "relationships": {
      "environment": {
        "data": {
          "type": "environments",
          "id": "env-sfuari395m7sck1"
        }
      }
    }
  }
}
Status Codes
  • 201 Created

    Success.

    Example Respone:

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data": {
        "attributes": {
          "auto-apply": true,
          "created-at": "2020-11-10T22:57:51Z",
          "lock-reason": null,
          "locked": false,
          "name": "vcs-less",
          "operations": true,
          "outputs": null,
          "queue-all-runs": false,
          "resources": null,
          "tags": null,
          "terraform-version": "0.13.5",
          "vcs-repo": null,
          "working-directory": null
        },
        "id": "ws-t68bpgu1vetpdh8",
        "links": {
          "self": "https://my.scalr.io/api/iacp/v3/workspaces/ws-t68bpgu1vetpdh8"
        },
        "relationships": {
          "configuration-version": null,
          "created-by": {
            "data": {
              "id": "user-stp8qjcvjljlo1o",
              "type": "users"
            }
          },
          "current-run": null,
          "environment": {
            "data": {
              "id": "env-sfuari395m7sck1",
              "type": "environments"
            }
          },
          "latest-configuration-version": null,
          "latest-run": null,
          "locked-by": null,
          "vcs-provider": null
        },
        "type": "workspaces"
      },
      "included": null,
      "meta": null
    }
    

  • 404 Not Found – Environment 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.

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 a Workspace

DELETE /workspaces/{workspace}
Parameters
  • workspace (string) – The ID of the workspace to be deleted.

Status Codes
  • 204 No Content – Successfully deleted the workspace.

  • 404 Not Found – Workspace 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 a Workspace

GET /workspaces/{workspace}

Show details of a specific workspace.

Parameters
  • workspace (string) – The workspace ID to show.

Query Parameters
  • include (array) – The comma-separated list of relationship paths. (Available values: agent-pool, configuration-version, created-by, environment, latest-configuration-version, latest-run, locked-by, locked-by-run, module-version, tags, updated-by, vcs-provider)

Example Request:

GET /workspaces/{workspace} HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK – Success.

  • 404 Not Found – Workspace 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 a Workspace

PATCH /workspaces/{workspace}
Parameters
  • workspace (string) – The ID of the workspace to be updated.

Request body:

Key path

Description

data.type* (string)

Available values: workspaces

data.attributes.auto-apply (boolean)

Indicates whether terraform apply should automatically run when terraform plan ends without error. Default false.

data.attributes.auto-queue-runs (object)

Available values: always, never, skip_first

Indicates if runs have to be queued automatically when a new configuration version is uploaded. skip_first - after the very first configuration version is uploaded into the workspace the run will not be triggered.

But the following configurations will do. This is the default behavior.

always - runs will be triggered automatically on every upload of the configuration version. never - configuration versions are uploaded into the workspace, but runs will not be triggered.

data.attributes.execution-mode (string)

Available values: remote, local

Which execution mode to use. Valid values are remote and local. When set to local, the workspace will be used for state storage only.

data.attributes.force-latest-run (boolean)

Indicates whether force run should automatically apply to latest run. Default false.

data.attributes.global-remote-state (boolean)

Specifies if the state is globally shared within the environment.

data.attributes.hooks.post-apply (string)

Command that should be run after terraform apply operation executed.

data.attributes.hooks.post-plan (string)

Command that should be run after terraform plan operation executed.

data.attributes.hooks.pre-apply (string)

Command that should be run before terraform apply operation executed.

data.attributes.hooks.pre-init (string)

Command that should be run before terraform init operation executed.

data.attributes.hooks.pre-plan (string)

Command that should be run before terraform plan operation executed.

data.attributes.name* (string)

Workspace name which must be unique within the environment.

Comprises letters, numbers, -, and _ only.

data.attributes.operations (boolean)

The attribute operations is deprecated. Use execution-mode instead.

data.attributes.run-operation-timeout (integer)

The timeout for the Terraform Run operations (in minutes).

data.attributes.terraform-version (string)

The version of Terraform the workspace performs runs on. If omitted, the system default version is assigned.

data.attributes.var-files (array)

data.attributes.vcs-repo.branch (string)

Branch of a repository the workspace is associated with. If omitted, the repository default branch will be used.

data.attributes.vcs-repo.dry-runs-enabled (boolean)

When true once a pull request into the vcs-repo.branch is opened, every push to a pull request’s branch will trigger a dry run in the workspace. Default true

data.attributes.vcs-repo.identifier* (string)

A reference to your VCS repository.

For GitHub, GitHub Enterprise and GitLab the format is <org>/<repo>. Azure DevOps Services has the format <org>/<project>/<repo>.

data.attributes.vcs-repo.ingress-submodules (boolean)

Specifies whether git submodules should be fetched when cloning the VCS repository.

data.attributes.vcs-repo.path (string)

The attribute vcs-repo.path is deprecated. Use working-directory and trigger-prefixes instead.

data.attributes.vcs-repo.trigger-prefixes (array)

List of paths (relative to the configuration version root), whose changes will trigger a run for the workspace using this binding when the CV is created. If omitted, any change in he configuration version root will trigger a new run.

data.attributes.working-directory (string)

A relative path where Terraform commands will execute in.

data.relationships.agent-pool (object)

The ID of the agent pool.

data.relationships.agent-pool.data.type* (string)

Available values: agent-pools

data.relationships.agent-pool.data.id* (string)

data.relationships.environment (object)

The environment this workspace belongs to.

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

Available values: environments

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

data.relationships.module-version (object)

The ID of the module version.

data.relationships.module-version.data.type* (string)

Available values: module-versions

data.relationships.module-version.data.id* (string)

data.relationships.tags.data* (array)

data.relationships.vcs-provider (object)

VCS provider of the Run’s workspace

data.relationships.vcs-provider.data.type* (string)

Available values: vcs-providers

data.relationships.vcs-provider.data.id* (string)

Example Request:

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

{
    "data": {
        "attributes": {
            "auto-apply": true,
            "auto-queue-runs": "always",
            "execution-mode": "remote",
            "force-latest-run": true,
            "global-remote-state": true,
            "hooks": {
                "post-apply": "string",
                "post-plan": "string",
                "pre-apply": "string",
                "pre-init": "string",
                "pre-plan": "string"
            },
            "name": "string",
            "operations": true,
            "run-operation-timeout": 1,
            "terraform-version": "string",
            "var-files": [
                "string"
            ],
            "vcs-repo": {
                "branch": "string",
                "dry-runs-enabled": true,
                "identifier": "string",
                "ingress-submodules": true,
                "path": "string",
                "trigger-prefixes": [
                    "string"
                ]
            },
            "working-directory": "string"
        },
        "relationships": {
            "agent-pool": {
                "data": {
                    "id": "string",
                    "type": "agent-pools"
                }
            },
            "environment": {
                "data": {
                    "id": "string",
                    "type": "environments"
                }
            },
            "module-version": {
                "data": {
                    "id": "string",
                    "type": "module-versions"
                }
            },
            "tags": {
                "data": [
                    {
                        "id": "string",
                        "type": "tags"
                    }
                ]
            },
            "vcs-provider": {
                "data": {
                    "id": "string",
                    "type": "vcs-providers"
                }
            }
        },
        "type": "workspaces"
    }
}
Status Codes
  • 200 OK – Success.

  • 404 Not Found – Workspace 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.

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)

Lock a Workspace

POST /workspaces/{workspace}/actions/lock

This endpoint locks a workspace.

Parameters
  • workspace (string) – The workspace ID to lock.

Example Request:

POST /workspaces/{workspace}/actions/lock HTTP/1.1
Host: my.scalr.io
Content-Type: application/json
Prefer: profile=preview

{
    "reason": "string"
}
Status Codes
  • 200 OK – Successfully locked the workspace.

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

  • 409 Conflict – Workspace already locked.

  • 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)

Resync a Workspace

POST /workspaces/{workspace}/actions/resync

This endpoint triggers a Configuration Version resync for a Workspace associated with a VCS repository.

Parameters
  • workspace (string) – The ID of the workspace to resync.

Status Codes
  • 201 Created – Success.

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

  • 409 Conflict – Workspace is not bound to any repository.

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

  • 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)

Set scheduled runs for the workspace

POST /workspaces/{workspace}/actions/set-schedule
Parameters
  • workspace (string) – The ID of the workspace to be updated.

Example Request:

POST /workspaces/{workspace}/actions/set-schedule HTTP/1.1
Host: my.scalr.io
Content-Type: application/json
Prefer: profile=preview

{
    "apply-schedule": "string",
    "destroy-schedule": "string"
}
Status Codes
  • 200 OK – Success.

  • 404 Not Found – Workspace 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.

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)

Unlock a Workspace

POST /workspaces/{workspace}/actions/unlock

This endpoint unlocks a workspace.

Parameters
  • workspace (string) – The workspace ID to unlock.

Status Codes
  • 200 OK – Successfully unlocked the workspace.

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

  • 409 Conflict – Workspace already unlocked, or locked by a different user.

  • 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 workspace’s tags

DELETE /workspaces/{workspace}/relationships/tags

This endpoint removes given tags from the workspace.

Parameters
  • workspace (string) – The workspace 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 /workspaces/{workspace}/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 workspace’s tags

GET /workspaces/{workspace}/relationships/tags

This endpoint returns a list of tags, assigned to a workspace.

Parameters
  • workspace (string) – The workspace to list tags for.

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

  • page[size] (string) – Page size

Example Request:

GET /workspaces/{workspace}/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-u3cp00tsrhhq2i0",
          "type": "tags"
        },
        {
          "id": "tag-u3cp040u14v64a8",
          "type": "tags"
        }
      ],
      "links": {
        "self": "https://my.scalr.io/api/iacp/v3/workspaces/ws-u3cp0pko9096sao/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 workspace’s tags

PATCH /workspaces/{workspace}/relationships/tags

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

Parameters
  • workspace (string) – The workspace 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 /workspaces/{workspace}/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 /workspaces/{workspace}/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 workspace

POST /workspaces/{workspace}/relationships/tags

This endpoint assigns the list of tags to the workspace.

Parameters
  • workspace (string) – The workspace 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 /workspaces/{workspace}/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)