# Workspace

This endpoint is used to create, update, search or delete workspace information inside a Terrakube organization.

{% hint style="warning" %}
To use this endpoint you should have "manageWorkspace" access at team level and a Terrakube organization
{% endhint %}

### Entity fields:

| Path                             | Type    | Description                                    |
| -------------------------------- | ------- | ---------------------------------------------- |
| data.type                        | string  | Should be "workspace"                          |
| data.attributes.name             | string  | Unique workspace for an Terrakube organization |
| data.attributes.branch           | boolean | Git branch to be used                          |
| data.attributes.source           | boolean | Git repository to be used                      |
| data.attributes.terraformVersion | boolean | Terraform version to run the workspace         |
| data.relationships.vcs.data.type | string  | Should be "vcs" (OPTIONAL)                     |
| data.relationships.vcs.data.type | string  | Should be the VCS Connection Id (OPTIONAL)     |

### Example:

```
{
    "data": {
        "type": "workspace",
        "attributes": {
            "branch": "main",
            "name": "Terrakube Workspace",
            "source": "https://github.com/AzBuilder/terraform-sample-repository.git",
            "terraformVersion": "0.15.0"
        },
        "relationships": {
            "vcs": {
                "data": {
                    "type": "vcs",
                    "id": "{{vcsIdGitHub}}"
                }
            }
        }
    }
}
```

### Supported Operations

## GET /organization/{organizationId}/workspace/{workspaceId}

> Returns an instance of type workspace

```json
{"openapi":"3.0.1","info":{"title":"Elide Service","version":"0.0.1"},"tags":[{"name":"workspace"}],"servers":[{"url":"/api/v1"}],"paths":{"/organization/{organizationId}/workspace/{workspaceId}":{"get":{"tags":["workspace"],"description":"Returns an instance of type workspace","parameters":[{"name":"fields[workspace]","in":"query","description":"Selects the set of workspace fields that should be returned in the result.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["allowRemoteApply","branch","createdBy","createdDate","defaultTemplate","deleted","description","executionMode","folder","iacType","lockDescription","locked","moduleSshKey","name","source","terraformVersion","updatedBy","updatedDate","access","agent","history","job","organization","reference","schedule","ssh","variable","vcs","webhook","workspaceTag"]}}},{"name":"include","in":"query","description":"Selects the set of relationships that should be expanded as a compound document in the result.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["access","agent","history","job","organization","reference","schedule","ssh","variable","vcs","webhook","workspaceTag"]}}}],"responses":{"200":{"description":"Successful response","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/workspace"},"included":{"uniqueItems":true,"type":"array","description":"Included resources","items":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object"},"relationships":{"type":"object"}}}}}}}}}}}}},"components":{"schemas":{"workspace":{"type":"object","properties":{"type":{"type":"string","description":"Create Permissions : (team manage workspace)\nDelete Permissions : (team manage workspace)"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"allowRemoteApply":{"type":"boolean","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"branch":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"createdBy":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"createdDate":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"defaultTemplate":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"deleted":{"type":"boolean","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"description":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"executionMode":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"folder":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"iacType":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"lockDescription":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"locked":{"type":"boolean","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"moduleSshKey":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"name":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"source":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"terraformVersion":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"updatedBy":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false},"updatedDate":{"type":"string","description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false}}},"relationships":{"type":"object","properties":{"access":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["access"]},"id":{"type":"string"}},"description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (user is a superuser)","readOnly":false,"writeOnly":false}}}},"agent":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["agent"]},"id":{"type":"string"}},"description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false}}}},"history":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["history"]},"id":{"type":"string"}},"description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (user is a super service)","readOnly":false,"writeOnly":false}}}},"job":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["job"]},"id":{"type":"string"}},"description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team view workspace OR team limited view workspace)","readOnly":false,"writeOnly":false}}}},"organization":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["organization"]},"id":{"type":"string"}},"description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false}}}},"reference":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["reference"]},"id":{"type":"string"}},"description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false}}}},"schedule":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["schedule"]},"id":{"type":"string"}},"description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false}}}},"ssh":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["ssh"]},"id":{"type":"string"}},"description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false}}}},"variable":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["variable"]},"id":{"type":"string"}},"description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false}}}},"vcs":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["vcs"]},"id":{"type":"string"}},"description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false}}}},"webhook":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["webhook"]},"id":{"type":"string"}},"description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false}}}},"workspaceTag":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["workspacetag"]},"id":{"type":"string"}},"description":"Read Permissions : (team view workspace OR team limited view workspace)\nUpdate Permissions : (team manage workspace OR team limited manage workspace)","readOnly":false,"writeOnly":false}}}}}}}}}}}
```

{% openapi src="<https://raw.githubusercontent.com/AzBuilder/azb-server/main/openapi-spec/v1_3.yml>" path="/organization/{organizationId}/workspace" method="post" %}
<https://raw.githubusercontent.com/AzBuilder/azb-server/main/openapi-spec/v1_3.yml>
{% endopenapi %}

{% openapi src="<https://raw.githubusercontent.com/AzBuilder/azb-server/main/openapi-spec/v1_3.yml>" path="/organization/{organizationId}/workspace/{workspaceId}" method="delete" %}
<https://raw.githubusercontent.com/AzBuilder/azb-server/main/openapi-spec/v1_3.yml>
{% endopenapi %}

{% openapi src="<https://raw.githubusercontent.com/AzBuilder/azb-server/main/openapi-spec/v1_3.yml>" path="/organization/{organizationId}/workspace/{workspaceId}" method="patch" %}
<https://raw.githubusercontent.com/AzBuilder/azb-server/main/openapi-spec/v1_3.yml>
{% endopenapi %}

{% hint style="info" %}
For a complete list of organization operation please visit the [OpenAPI specification](https://github.com/AzBuilder/terrakube-server/tree/main/openapi-spec)
{% endhint %}