workspaces

Launch Workspace Session

Launch a daemon-backed coding session for the given workspace.

post/api/v1/workspaces/{workspace_id}/sessions

Request

  • Base URL: https://docs.omnara.com (the document declares no server; this is the origin it was published from)
  • URL: https://docs.omnara.com/api/v1/workspaces/{workspace_id}/sessions
  • Auth: HTTP bearer

Path parameters

workspace_idstring required

Request body

machine_idstring nullable

Machine ID to launch the session on. If not provided, uses the workspace's default machine.

user_session_idstring nullable

Existing user session to reuse

metadataobject nullable

Arbitrary metadata describing the launch

initial_promptstring nullable

Prompt delivered to the coding agent at startup

worktree_namestring nullable

Name for the git worktree/branch to use for this session

resume_session_idstring nullable

SDK session ID to resume from (e.g., from Claude CLI import)

agent_session_idstring nullable

Existing agent session ID to connect to (e.g., from import)

Response

Successful Response

statusstring required

Launch status (e.g., 'ok', 'error')

payloadobject nullable

Optional response payload with additional details

Changes

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