> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces SDK Reference

> SDK reference for the Workspaces API, available in Node.js and Python.

## Workspaces

### List Workspaces

Returns workspaces the caller can access. A user session lists every membership. A management key lists only the workspace bound to the key. Project keys are rejected.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.workspaces.list()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.workspaces.list();

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "limit": Optional[int],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": str,
        "data": [{
            "id": str,
            "key": str,
            "display_name": str,
            "logo_url": Optional[str],
            "archived_on": str,  # optional
            "archived_by_id": Optional[str],
            "organization": {  # optional
                "id": Optional[str],
                "key": Optional[str],
            },
            "settings": {  # optional
                "same_project_entities_enabled": Optional[bool],
                "model_garden_settings": Dict[str, Any],  # optional
                "plugins": Dict[str, Any],  # optional
            },
            "sidebar_version": Optional[str],
            "features": Dict[str, Any],  # optional
            "total_members": Optional[int],
            "metadata": Dict[str, Any],  # optional
            "capabilities": {  # optional
                "roles": List[str],  # optional
                "projects": List[str],  # optional
            },
        }],
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: {
        id: string;
        key: string;
        displayName: string;
        logoUrl?: string;
        archivedOn?: Date;
        archivedById?: string;
        organization?: {
          id?: string;
          key?: string;
        };
        settings?: {
          sameProjectEntitiesEnabled?: boolean;
          modelGardenSettings?: Record<string, unknown>;
          plugins?: Record<string, unknown>;
        };
        sidebarVersion?: string;
        features?: Record<string, unknown>;
        totalMembers?: number;
        metadata?: Record<string, unknown>;
        capabilities?: {
          roles?: string[];
          projects?: string[];
        };
      }[];
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve a Workspace

Retrieves a workspace by its key. A user session must be a member and does not need a workspace-scoped token. A management key may only retrieve the workspace bound to the key.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.workspaces.get(key="<key>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.workspaces.get({
      key: "<key>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "key": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      key: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "workspace": {
            "id": str,
            "key": str,
            "display_name": str,
            "logo_url": Optional[str],
            "archived_on": str,  # optional
            "archived_by_id": Optional[str],
            "organization": {  # optional
                "id": Optional[str],
                "key": Optional[str],
            },
            "settings": {  # optional
                "same_project_entities_enabled": Optional[bool],
                "model_garden_settings": Dict[str, Any],  # optional
                "plugins": Dict[str, Any],  # optional
            },
            "sidebar_version": Optional[str],
            "features": Dict[str, Any],  # optional
            "total_members": Optional[int],
            "metadata": Dict[str, Any],  # optional
            "capabilities": {  # optional
                "roles": List[str],  # optional
                "projects": List[str],  # optional
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      workspace: {
        id: string;
        key: string;
        displayName: string;
        logoUrl?: string;
        archivedOn?: Date;
        archivedById?: string;
        organization?: {
          id?: string;
          key?: string;
        };
        settings?: {
          sameProjectEntitiesEnabled?: boolean;
          modelGardenSettings?: Record<string, unknown>;
          plugins?: Record<string, unknown>;
        };
        sidebarVersion?: string;
        features?: Record<string, unknown>;
        totalMembers?: number;
        metadata?: Record<string, unknown>;
        capabilities?: {
          roles?: string[];
          projects?: string[];
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Update a Workspace

Partially updates a workspace. Omit a field to leave it unchanged. Set `archived` to true to archive, false to restore. The workspace key cannot be changed.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.workspaces.update(key="<key>", display_name="Production")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.workspaces.update({
      key: "<key>",
      updateWorkspaceRequest: {
        displayName: "Production",
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "key": str,  # required
        "display_name": Optional[str],
        "logo_url": Optional[str],
        "archived": Optional[bool],
        "settings": {  # optional
            "same_project_entities_enabled": Optional[bool],
            "model_garden_settings": Dict[str, Any],  # optional
            "plugins": Dict[str, Any],  # optional
        },
        "metadata": Dict[str, Any],  # optional
        "enforce_enabled_models": Optional[bool],
        "chat_kit": {  # optional
            "items": [{  # optional
                "id": Optional[str],
                "display_name": Optional[str],
                "resource_id": Optional[str],
                "resource_type": Optional[str],
            }],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      key: string;  // required
      updateWorkspaceRequest: {  // required
        displayName?: string;
        logoUrl?: string;
        archived?: boolean;
        settings?: {
          sameProjectEntitiesEnabled?: boolean;
          modelGardenSettings?: Record<string, unknown>;
          plugins?: Record<string, unknown>;
        };
        metadata?: Record<string, unknown>;
        enforceEnabledModels?: boolean;
        chatKit?: {
          items?: {
            id?: string;
            displayName?: string;
            resourceId?: string;
            resourceType?: string;
          }[];
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "workspace": {
            "id": str,
            "key": str,
            "display_name": str,
            "logo_url": Optional[str],
            "archived_on": str,  # optional
            "archived_by_id": Optional[str],
            "organization": {  # optional
                "id": Optional[str],
                "key": Optional[str],
            },
            "settings": {  # optional
                "same_project_entities_enabled": Optional[bool],
                "model_garden_settings": Dict[str, Any],  # optional
                "plugins": Dict[str, Any],  # optional
            },
            "sidebar_version": Optional[str],
            "features": Dict[str, Any],  # optional
            "total_members": Optional[int],
            "metadata": Dict[str, Any],  # optional
            "capabilities": {  # optional
                "roles": List[str],  # optional
                "projects": List[str],  # optional
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      workspace: {
        id: string;
        key: string;
        displayName: string;
        logoUrl?: string;
        archivedOn?: Date;
        archivedById?: string;
        organization?: {
          id?: string;
          key?: string;
        };
        settings?: {
          sameProjectEntitiesEnabled?: boolean;
          modelGardenSettings?: Record<string, unknown>;
          plugins?: Record<string, unknown>;
        };
        sidebarVersion?: string;
        features?: Record<string, unknown>;
        totalMembers?: number;
        metadata?: Record<string, unknown>;
        capabilities?: {
          roles?: string[];
          projects?: string[];
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>