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

# Creating Workspaces

> Create a workspace before making any data changes, then use the workspace_id to scope all write operations.

Before running scrapers, editing SQL models, or making any pipeline changes, create a workspace. All write operations require a `workspace_id`.

## Create a workspace

<Steps>
  <Step title="Call workspace_manage with operation='create'">
    Pass a `scraper_name` to clone scraper data, or omit it for a SQL-only workspace.

    **Scraper-based workspace** — clones production data for a specific scraper:

    ```python theme={null}
    workspace_manage(
        operation="create",
        scraper_name="pa_medicaid_enrollment",
        name="medicaid-q1-update",
        description="Q1 enrollment refresh"
    )
    ```

    **SQL-only workspace** — no data cloning, for model development:

    ```python theme={null}
    workspace_manage(
        operation="create",
        name="star-ratings-model",
        description="New star ratings gold model"
    )
    ```
  </Step>

  <Step title="Save the workspace_id from the response">
    The response tells you what was created:

    ```
    Created workspace
    ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    Scraper: pa_medicaid_enrollment
    Tables cloned: files, schema_mappings, value_mappings, warehouse_tables
    ```

    For a SQL-only workspace:

    ```
    Created workspace
    ID: b2c3d4e5-f6a7-8901-bcde-f12345678901
    Type: SQL-only (no scraper)
    ```

    Copy the `ID` — you'll pass it as `workspace_id` to every subsequent tool call.
  </Step>
</Steps>

<Note>
  All pipeline write operations require `workspace_id`. This includes `scraper_run`, `extraction_run`, `validation_run`, `warehouse_manage`, `sql_model_save`, and any other tool that modifies data.
</Note>

## Clone from another workspace

Use `from_workspace_id` to branch off an existing workspace instead of starting from production. This copies the source workspace's SQL models and scraper data into a new workspace.

```python theme={null}
workspace_manage(
    operation="create",
    scraper_name="pa_medicaid_enrollment",
    from_workspace_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    name="medicaid-q1-hotfix"
)
```

This is useful when you want to iterate on work already in progress without modifying the original workspace.

## List your workspaces

To see all active workspaces:

```python theme={null}
workspace_manage(operation="list")
```

To filter by scraper:

```python theme={null}
workspace_manage(
    operation="list",
    scraper_name="pa_medicaid_enrollment"
)
```

Example output:

```
Workspaces (2):
  pa_medicaid_enrollment — medicaid-q1-update
    ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    Created: 2026-04-07 09:12:34

  pa_medicaid_enrollment — medicaid-q4-update [PROMOTED]
    ID: 9f8e7d6c-5b4a-3210-fedc-ba9876543210
    Created: 2026-03-28 14:05:11
```

Promoted workspaces are shown with a `[PROMOTED]` label and cannot be deleted.

## Delete a workspace

When you're done with a workspace and don't want to promote it, delete it to clean up:

```python theme={null}
workspace_manage(
    operation="delete",
    workspace_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
)
```

You cannot delete a workspace that has already been promoted.