# Workspace

## Queries

***

### <mark style="background-color:yellow;">get\_workspace</mark>

Get workspace details.

#### Parameters

* `id` (required): The ID of the workspace.

#### Example

```bash
curl -X POST 'https://app.polyteia.com/api' \
    -header "Content-Type: application/json" \
    -header "Authorization: Bearer <your_access_token>" \
    --data '{
        "query": "get_workspace",
        "params": {
            "id": "ws_cv33u4n0i6q45p93i930"
        }
    }'
```

#### **Workspace Response**

* `id`: The ID of the workspace.
* `organization_id`: The ID of the organization workspace belongs to.
* `created_at`: The date and time when the workspace was created.
* `updated_at`: The date and time when the workspace was last updated.
* `name`: The name of the workspace.
* `description`: The description of the workspace.
* `attributes`: Any optional key value pairs associated with the workspace.

#### Example Response

```json
{
    "data": {
        "id": "ws_cv33u4n0i6q45p93i930",
        "organization_id": "org_cv33u4n0i6q45p93i930",
        "created_at": "2025-03-24T15:12:49.186202Z",
        "updated_at": "2025-03-24T20:01:59.408382Z",
        "name": "Finance",
        "description": "Finance department workspace",
        "attributes": {
            "key": "value"
        }
    }
}
```

***

### <mark style="background-color:yellow;">list\_workspaces</mark>

Paginated list of all workspaces subject to the user's access rights.

#### Parameters

* `page` (required): The page number to return. `minimum: 1`
* `size` (required): The number of items to return per page. `minimum: 1, maximum: 100`

#### Example

```bash
curl -X POST 'https://app.polyteia.com/api' \
    -header "Content-Type: application/json" \
    -header "Authorization: Bearer <your_access_token>" \
    --data '{
        "query": "list_workspaces",
        "params": {
            "page": 1,
            "size": 10
        }
    }'
```

#### Response

* `total`: The total number of workspaces subject to the user's access rights.
* `page`: The current page number.
* `size`: The number of items requested per page.
* `items`: An array of workspaces. See [Workspace Response](#workspace-response) for more details.

#### Example Response

```json
{
    "data": {
        "total": 1,
        "page": 1,
        "size": 100,
        "items": [
            {
                "id": "ws_cv33u4n0i6q45p93i930",
                "organization_id": "org_cv33u4n0i6q45p93i930",
                "created_at": "2025-03-24T15:12:49.186202Z",
                "updated_at": "2025-03-24T20:01:59.408382Z",
                "name": "Finance",
                "description": "Finance department workspace"
            }
        ]
    }
}
```

## Commands

***

### <mark style="background-color:yellow;">create\_workspace</mark>

Use this command to create a new workspace.

#### Parameters

* `organization_id` (required): The ID of the organization to create the workspace in.
* `name` (required): Name of the workspace. `minimum: 1` `maximum: 50` `unicode characters only`
* `description` (optional): Description of the workspace. `maximum: 255` `unicode characters only`
* `attributes` (optional): Any optional key value pairs to be associated with the workspace.

#### Example

```bash
curl -X POST 'https://app.polyteia.com/api' \
    -header "Content-Type: application/json" \
    -header "Authorization: Bearer <your_access_token>" \
    --data '{
        "query": "create_workspace",
        "params": {
            "organization_id": "org_cv33u4n0i6q45p93i930",
            "name": "Finance",
            "description": "Finance department workspace",
            "attributes": {
                "key1": "value1",
                "key2": 100,
                "key3": {
                    "nested": true
                }
            }
        }
    }'
```

#### Response

The response is the [Workspace Response](#workspace-response) of the created workspace.

#### Example Response

```json
{
    "data": {
        "id": "ws_cv33u4n0i6q45p93i930",
        "organization_id": "org_cv33u4n0i6q45p93i930",
        "created_at": "2025-03-24T15:12:49.186202Z",
        "updated_at": "2025-03-24T20:01:59.408382Z",
        "name": "Finance",
        "description": "Finance department workspace",
        "attributes": {
            "key": "value"
        }
    }
}
```

Ensure to store the `id` for future reference or updates to the workspace.

***

### <mark style="background-color:yellow;">update\_workspace</mark>

Use this command to update a workspace.

#### Parameters

* `id` (required): The ID of the workspace to update.
* `name` (required): The name of the workspace.
* `description` (optional): The description of the workspace.
* `attributes` (optional): A JSON object of key-value pairs to add to the workspace.

#### Example

```bash
curl -X POST 'https://app.polyteia.com/api' \
    -header "Content-Type: application/json" \
    -header "Authorization: Bearer <your_access_token>" \
    --data '{
        "query": "update_workspace",
        "params": {
            "id": "ws_cv33u4n0i6q45p93i930",
            "name": "My Workspace",
            "description": "My Workspace Description",
            "attributes": {
                "key": "new_value"
            }
        }
    }'
```

#### Response

The response is the [Workspace Response](#workspace-response) of the updated workspace.

#### Example Response

```json
{
    "data": {
        "id": "ws_cv33u4n0i6q45p93i930",
        "organization_id": "org_cv33u4n0i6q45p93i930",
        "created_at": "2025-03-24T15:12:49.186202Z",
        "updated_at": "2025-03-24T20:01:59.408382Z",
        "name": "My Workspace",
        "description": "My Workspace Description",
        "attributes": {
            "key": "new_value"
        }
    }
}
```

***

### <mark style="background-color:yellow;">delete\_workspace</mark>

Use this command to delete a workspace.

{% hint style="danger" %}
**This action is irreversible. Use this command with caution.**
{% endhint %}

#### Parameters

* `id` (required): The ID of the workspace to delete.

#### Example

```bash
curl -X POST 'https://app.polyteia.com/api' \
    -header "Content-Type: application/json" \
    -header "Authorization: Bearer <your_access_token>" \
    --data '{
        "query": "delete_workspace",
        "params": {
            "id": "ws_cv33u4n0i6q45p93i930"
        }
    }'
```

#### Response

```json
{
    "data": {
        "id": "ws_cv33u4n0i6q45p93i930"
    }
}
```

* `id`: The ID of the workspace that was deleted.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.polyteia.com/api-docs/en/workspace.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.