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

# Workspaces

> SDK methods to list, create, and manage workspaces that organize deployments on a cluster.

## Methods

<Accordion title="list">
  List workspaces associated with the user. Optional filters include clusterId, fqn, and workspace name.

  #### Parameters

  <ParamField body="limit" type="typing.Optional[int]">
    Number of items per page
  </ParamField>

  <ParamField body="offset" type="typing.Optional[int]">
    Number of items to skip
  </ParamField>

  <ParamField body="cluster_id" type="typing.Optional[str]">
    ClusterId of the Cluster
  </ParamField>

  <ParamField body="name" type="typing.Optional[str]">
    Workspace Name
  </ParamField>

  <ParamField body="fqn" type="typing.Optional[str]">
    Workspace FQN
  </ParamField>

  <ParamField body="include_cluster" type="typing.Optional[bool]">
    When true, each workspace includes cluster information
  </ParamField>

  #### Returns

  <ResponseField name="SyncPager[Workspace, ListWorkspacesResponse]" type="SyncPager[Workspace, ListWorkspacesResponse]">
    [🔗 ListWorkspacesResponse](/docs/truefoundry_sdk/types#listworkspacesresponse)

    Returns all the workspaces associated with a user and also the response includes paginated data.
  </ResponseField>

  #### Usage

  ```python lines theme={"dark"}
  from truefoundry import TrueFoundry

  client = TrueFoundry(
      api_key="YOUR_API_KEY",
      base_url="https://yourhost.com/path/to/api",
  )

  client.workspaces.list(
      limit=10,
      offset=10,
      cluster_id="cluster_id_value",
      name="value",
      fqn="value",
      include_cluster="value",
  )

  # Iterate through results
  for item in response:
      print(item.name)

  # Or paginate page by page
  for page in response.iter_pages():
      for item in page:
          print(item.name)
  ```
</Accordion>

<Accordion title="create_or_update">
  Creates a new workspace or updates an existing one based on the provided manifest.

  #### Parameters

  <ParamField body="manifest" type="WorkspaceManifest" required>
    [🔗 WorkspaceManifest](/docs/truefoundry_sdk/types#workspacemanifest)

    Workspace manifest
  </ParamField>

  <ParamField body="dry_run" type="typing.Optional[bool]">
    Dry run the request
  </ParamField>

  #### Returns

  <ResponseField name="GetWorkspaceResponse" type="GetWorkspaceResponse">
    [🔗 GetWorkspaceResponse](/docs/truefoundry_sdk/types#getworkspaceresponse)

    * Creates or updates a workspace with given manifest
    * Corresponding authorization entry with admin role is made using newly created workspace
    * Attached with the cluster id where the workspace is created
  </ResponseField>

  #### Usage

  ```python lines theme={"dark"}
  from truefoundry import TrueFoundry

  client = TrueFoundry(
      api_key="YOUR_API_KEY",
      base_url="https://yourhost.com/path/to/api",
  )

  client.workspaces.create_or_update(
      manifest={"key": "value"},
      dry_run=False,
  )
  ```
</Accordion>

<Accordion title="search">
  List workspaces the user can read with optional structured `filter` (name, id, environmentId, cluster\_fqn) and pagination.

  #### Parameters

  <ParamField body="limit" type="typing.Optional[int]">
    Number of items per page
  </ParamField>

  <ParamField body="offset" type="typing.Optional[int]">
    Number of items to skip
  </ParamField>

  <ParamField body="filter" type="typing.Optional[str]">
    JSON string containing array of search filters with string, type and operator
  </ParamField>

  <ParamField body="include_cluster" type="typing.Optional[bool]">
    When true, each workspace includes cluster information
  </ParamField>

  #### Returns

  <ResponseField name="SyncPager[Workspace, ListWorkspacesResponse]" type="SyncPager[Workspace, ListWorkspacesResponse]">
    [🔗 ListWorkspacesResponse](/docs/truefoundry_sdk/types#listworkspacesresponse)

    Paginated workspaces matching the filter.
  </ResponseField>

  #### Usage

  ```python lines theme={"dark"}
  from truefoundry import TrueFoundry

  client = TrueFoundry(
      api_key="YOUR_API_KEY",
      base_url="https://yourhost.com/path/to/api",
  )

  client.workspaces.search(
      limit=10,
      offset=10,
      filter="value",
      include_cluster="value",
  )
  ```
</Accordion>

<Accordion title="get">
  Get workspace associated with provided workspace id

  #### Parameters

  <ParamField body="id" type="str" required>
    Workspace id of the space
  </ParamField>

  #### Returns

  <ResponseField name="GetWorkspaceResponse" type="GetWorkspaceResponse">
    [🔗 GetWorkspaceResponse](/docs/truefoundry_sdk/types#getworkspaceresponse)

    Returns the workspaces associated with provided workspace id
  </ResponseField>

  #### Usage

  ```python lines theme={"dark"}
  from truefoundry import TrueFoundry

  client = TrueFoundry(
      api_key="YOUR_API_KEY",
      base_url="https://yourhost.com/path/to/api",
  )

  client.workspaces.get(
      id="id_value",
  )
  ```
</Accordion>

<Accordion title="delete">
  Deletes the workspace with the given workspace ID.

  #### Parameters

  <ParamField body="id" type="str" required>
    Workspace id of the space
  </ParamField>

  #### Returns

  <ResponseField name="WorkspacesDeleteResponse" type="WorkspacesDeleteResponse">
    [🔗 WorkspacesDeleteResponse](/docs/truefoundry_sdk/types#workspacesdeleteresponse)

    Successfully deletes the workspace and returns the workspace details along with a confirmation message.
  </ResponseField>

  #### Usage

  ```python lines theme={"dark"}
  from truefoundry import TrueFoundry

  client = TrueFoundry(
      api_key="YOUR_API_KEY",
      base_url="https://yourhost.com/path/to/api",
  )

  client.workspaces.delete(
      id="id_value",
  )
  ```
</Accordion>

<Accordion title="get_by_fqn">
  Get Workspace by FQN.

  #### Parameters

  <ParamField body="fqn" type="str" required>
    FQN of the workspace
  </ParamField>

  #### Returns

  <ResponseField name="GetWorkspaceResponse" type="GetWorkspaceResponse">
    [🔗 GetWorkspaceResponse](/docs/truefoundry_sdk/types#getworkspaceresponse)

    Workspace details
  </ResponseField>

  #### Usage

  ```python lines theme={"dark"}
  from truefoundry import TrueFoundry

  client = TrueFoundry(
      api_key="YOUR_API_KEY",
      base_url="https://yourhost.com/path/to/api",
  )

  client.workspaces.get_by_fqn(
      fqn="value",
  )
  ```
</Accordion>