---
title: "Get Workspace By Id"
method: GET
path: "/api/v1/workspaces/{workspace_id}"
tags: ["workspaces"]
---

# Get Workspace By Id

`GET /api/v1/workspaces/{workspace_id}`

Get workspace by ID.

## Path parameters

- `workspace_id` string, required

## Response `200`

Successful Response

- WorkspaceDescriptor — Serialized workspace row returned to API clients.
  - `id` string, required — Unique workspace identifier
  - `user_id` string, required — Owner user identifier
  - `git_host` string, nullable — Canonical git host (e.g., github.com)
  - `git_path` string, nullable — Canonical git repository path (e.g., org/repo)
  - `workspace_metadata` object, nullable — Arbitrary workspace metadata (labels, annotations)
  - `workspace_config` WorkspaceConfigOutput — Workspace-level configuration persisted alongside metadata.
    - `git` GitSettings — Git-related settings for a workspace.
      - `remote` string — Git remote to use for push/pull operations (e.g., 'origin')
      - `base_ref` string — Base ref/branch for worktrees and checkpoint comparisons (e.g., 'main', 'master')
    - `sync` SyncSettings — Remote sync settings for a workspace. When enabled, checkpoints are automatically uploaded after each agent turn.
      - `enabled` boolean — Whether remote sync is enabled. When enabled, checkpoints are automatically uploaded after each agent turn.
    - `remote_env` RemoteEnvSettings — Remote environment settings for a workspace. Used to configure remote environments that can be spun up with specific ENV variables.
      - `env` EnvVar[] — Environment variables as structured key-value pairs for remote environments
        - `key` string, required — Environment variable name
        - `value` string, required — Environment variable value
    - `setup` SetupSettings — Setup script settings for a workspace. Configures an optional shell script that runs automatically: - On worktree creation (local machine) - On worktree migration (to/from sandbox) - On checkpoint restore The script runs with the worktree directory as the working directory.
      - `script` string, nullable — Path to a setup script (relative to workspace root) to run on worktree setup
  - `user_machine_paths` SharedSchemasApiWorkspacesUserMachinePathDescriptor[] — Machines linked to this workspace with their local paths
    - `user_machine_id` string, required — Identifier of the linked user machine
    - `local_path` string, required — Absolute filesystem path to the workspace on the machine
  - `created_at` string, date-time, required — Timestamp when the workspace was created
  - `updated_at` string, date-time, required — Timestamp when the workspace was last updated

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/omnara/apis/omnara-api.md) · [All operations](https://skmtc.dev/omnara/apis/omnara-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/omnara/omnara-api/revisions/624048e40cad/schema)