Sign in
workspaces

Ensure Workspace

Create or update a workspace and link it to a machine.

This endpoint:

  1. Finds or creates a workspace (by machine+path)
  2. Creates/updates the machine-workspace link with the local path
  3. Ensures a main worktree exists with the machine reference
post/api/v1/workspaces/ensure

Request body

machine_idstring required

Identifier of the daemon machine

local_pathstring required

Absolute path reported by the daemon

git_hoststring nullable

Canonical git host if detected (e.g., github.com)

git_pathstring nullable

Canonical git path if detected (e.g., org/repo)

workspace_metadataobject nullable

Optional workspace metadata (labels, annotations, etc.)

Response

Successful Response

idstring required

Unique workspace identifier

user_idstring required

Owner user identifier

git_hoststring nullable

Canonical git host (e.g., github.com)

git_pathstring nullable

Canonical git repository path (e.g., org/repo)

workspace_metadataobject nullable

Arbitrary workspace metadata (labels, annotations)

created_atstring date-time required

Timestamp when the workspace was created

updated_atstring date-time required

Timestamp when the workspace was last updated

Changes

No recorded changes to this endpoint across all 1 revision of this API.