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

# Workspaces

> List and manage scan workspaces

# Workspaces

## List Workspaces

Get a list of all run workspaces with full metadata.

**List workspaces from database (default):**

```bash theme={null}
curl http://localhost:8002/osm/api/workspaces \
  -H "Authorization: Bearer $TOKEN"
```

**List workspaces with pagination:**

```bash theme={null}
curl "http://localhost:8002/osm/api/workspaces?offset=0&limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

**List workspaces from filesystem/assets:**

```bash theme={null}
curl "http://localhost:8002/osm/api/workspaces?filesystem=true" \
  -H "Authorization: Bearer $TOKEN"
```

**Combine pagination with filesystem mode:**

```bash theme={null}
curl "http://localhost:8002/osm/api/workspaces?filesystem=true&offset=20&limit=10" \
  -H "Authorization: Bearer $TOKEN"
```

**Response (database mode):**

```json theme={null}
{
  "data": [
    {
      "id": 1,
      "name": "example.com",
      "local_path": "/home/user/osmedeus-base/workspaces/example.com",
      "total_assets": 150,
      "total_subdomains": 120,
      "total_urls": 500,
      "total_vulns": 12,
      "vuln_critical": 2,
      "vuln_high": 3,
      "vuln_medium": 4,
      "vuln_low": 3,
      "vuln_potential": 0,
      "risk_score": 7.5,
      "tags": ["production", "priority"],
      "last_run": "2025-01-15T10:30:00Z",
      "run_workflow": "subdomain-enum",
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "name": "test.com",
      "local_path": "/home/user/osmedeus-base/workspaces/test.com",
      "total_assets": 50,
      "total_subdomains": 35,
      "total_urls": 120,
      "total_vulns": 3,
      "vuln_critical": 0,
      "vuln_high": 1,
      "vuln_medium": 2,
      "vuln_low": 0,
      "vuln_potential": 5,
      "risk_score": 4.2,
      "tags": ["staging"],
      "last_run": "2025-01-14T15:00:00Z",
      "run_workflow": "port-scan",
      "created_at": "2025-01-12T12:00:00Z",
      "updated_at": "2025-01-14T15:00:00Z"
    }
  ],
  "pagination": {
    "total": 100,
    "offset": 0,
    "limit": 20
  }
}
```

**Workspace Fields Reference:**

| Field                   | Type      | Description                                |
| ----------------------- | --------- | ------------------------------------------ |
| `id`                    | int       | Unique workspace identifier                |
| `name`                  | string    | Workspace name (usually the target domain) |
| `local_path`            | string    | Full path to workspace directory           |
| `total_assets`          | int       | Total discovered assets                    |
| `total_subdomains`      | int       | Total discovered subdomains                |
| `total_urls`            | int       | Total discovered URLs                      |
| `total_vulns`           | int       | Total vulnerabilities found                |
| `vuln_critical`         | int       | Critical severity vulnerabilities          |
| `vuln_high`             | int       | High severity vulnerabilities              |
| `vuln_medium`           | int       | Medium severity vulnerabilities            |
| `vuln_low`              | int       | Low severity vulnerabilities               |
| `vuln_potential`        | int       | Potential/informational findings           |
| `risk_score`            | float     | Calculated risk score (0-10)               |
| `tags`                  | array     | Custom tags for organization               |
| `last_run`              | timestamp | Last workflow run timestamp                |
| `run_workflow`          | string    | Name of last executed workflow             |
| `state_execution_log`   | string    | Path to execution log file                 |
| `state_completed_file`  | string    | Path to completed marker file              |
| `state_workflow_file`   | string    | Path to workflow YAML file                 |
| `state_workflow_folder` | string    | Path to workflow folder                    |
| `created_at`            | timestamp | Workspace creation timestamp               |
| `updated_at`            | timestamp | Last update timestamp                      |

***

## List Workspace Names

Get a lightweight list of workspace names only (without full metadata).

```bash theme={null}
curl http://localhost:8002/osm/api/workspace-names \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json theme={null}
{
  "data": [
    "example.com",
    "test.com",
    "demo.org"
  ],
  "count": 3
}
```

***

## Get Workspace State File

Retrieve the content of a workspace state file. This endpoint provides access to execution logs, completion markers, and workflow files associated with a workspace.

**Get execution log:**

```bash theme={null}
curl "http://localhost:8002/osm/api/workspaces/example.com/state-file?state_file=execution_log" \
  -H "Authorization: Bearer $TOKEN"
```

**Get completed file:**

```bash theme={null}
curl "http://localhost:8002/osm/api/workspaces/example.com/state-file?state_file=completed_file" \
  -H "Authorization: Bearer $TOKEN"
```

**Get workflow file:**

```bash theme={null}
curl "http://localhost:8002/osm/api/workspaces/example.com/state-file?state_file=workflow_file" \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json theme={null}
{
  "workspace": "example.com",
  "state_file": "execution_log",
  "file_path": "/home/user/osmedeus-base/workspaces/example.com/log/execution.log",
  "content": "2025-01-15 10:30:00 [INFO] Starting workflow...\n2025-01-15 10:30:05 [INFO] Step 1 completed...\n..."
}
```

**State File Types:**

| Type             | Description                                            |
| ---------------- | ------------------------------------------------------ |
| `execution_log`  | Detailed execution log with timestamps and step output |
| `completed_file` | Marker file indicating workflow completion status      |
| `workflow_file`  | The YAML workflow definition that was executed         |

**Error Responses:**

| Status | Description                                             |
| ------ | ------------------------------------------------------- |
| 400    | Invalid workspace name or missing state\_file parameter |
| 403    | Path traversal attempt detected                         |
| 404    | Workspace or state file not found                       |