Skip to main content
POST
/
api
/
v1
/
workspaces
/
ensure
Ensure Workspace
curl --request POST \
  --url https://api.example.com/api/v1/workspaces/ensure \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "machine_id": "<string>",
  "local_path": "<string>",
  "git_host": "<string>",
  "git_path": "<string>",
  "workspace_metadata": {},
  "git_settings": {
    "remote": "origin",
    "base_ref": "main"
  }
}
'
{
  "id": "<string>",
  "user_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "git_host": "<string>",
  "git_path": "<string>",
  "workspace_metadata": {},
  "workspace_config": {
    "git": {
      "remote": "origin",
      "base_ref": "main"
    },
    "sync": {
      "enabled": false
    },
    "remote_env": {
      "env": [
        {
          "key": "<string>",
          "value": "<string>"
        }
      ]
    },
    "setup": {
      "script": "<string>"
    }
  },
  "user_machine_paths": [
    {
      "user_machine_id": "<string>",
      "local_path": "<string>"
    }
  ]
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Payload for creating or updating a workspace from the daemon.

machine_id
string
required

Identifier of the daemon machine

local_path
string
required

Absolute path reported by the daemon

git_host
string | null

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

git_path
string | null

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

workspace_metadata
Workspace Metadata · object

Optional workspace metadata (labels, annotations, etc.)

git_settings
GitSettings · object

Detected git settings (remote, base_ref) for the workspace

Response

Successful Response

Serialized workspace row returned to API clients.

id
string
required

Unique workspace identifier

user_id
string
required

Owner user identifier

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

git_host
string | null

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

git_path
string | null

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

workspace_metadata
Workspace Metadata · object

Arbitrary workspace metadata (labels, annotations)

workspace_config
WorkspaceConfig · object

Workspace configuration including git, sync, and remote environment settings

user_machine_paths
UserMachinePathDescriptor · object[]

Machines linked to this workspace with their local paths