---
title: "Create Workspace"
method: POST
path: "/agent-loop/workspaces"
tags: ["agent-loop"]
---

# Create Workspace

`POST /agent-loop/workspaces`

Create a new workspace OR (for Scott pushes) upsert one keyed on
`(captured_by_user_id, source_kind, source_id)`.

Two flows:
  - No `scott_push`: classic workspace creation. Single transaction.
  - With `scott_push`: idempotent. Same (user, source_kind, source_id)
    returns the same planspace. Push artifact metadata is replaced in
    place; scott_push turns are APPENDED past the existing chain tip
    (never deleted). Non-scott_push turns the user added in the Scott
    UI are never touched — they stay parented where the user put them
    and become branches at the prior tip after the next push.

## Request body

- CreateWorkspaceRequest
  - `id` string, nullable
  - `name` string, required
  - `description` string, nullable
  - `model` string, nullable
  - `system_prompt` string, nullable
  - `initial_doc_content` string
  - `initial_doc_label` string
  - `use_local_sandbox` boolean
  - `connected_sources` ConnectedSourceSelection[], nullable
    - `adapter` 'github' | 'slack' | 'uploaded_file', required — Type of source adapter (github, uploaded_file, etc.)
    - `selection` union, required
      - GitHubSourceSelection — User's selection when connecting a GitHub source
        - `repo` string, required
        - `branch` string, required
      - SlackSourceSelection — User's selection when connecting a Slack source
        - `slack_team_id` string, required
        - `channel_id` string, required
      - UploadedFileSourceSelection — User's selection when connecting an uploaded file source
        - `file_id` string, required
        - `visibility` 'private' | 'public' — Visibility level of a source
  - `scott_push` ScottPushSpec — Optional sub-object on `CreateWorkspaceRequest` that turns the call into a Scott push. Idempotent on `(captured_by_user_id, source_kind, source_id)`: same triple from the same user returns the same planspace, replacing the push payload and any scott_push turns in-place. See D6 in the scott-push-v2 design doc. The structured payload is a typed `ScottPushPayload` (mirroring `packages/scott-ext-core/src/types.ts` in `one-shot-core`). Strong typing here is what lets orval emit useful client types instead of `Record<string, unknown>`.
    - `name` string, required — Inferred title for the workspace + push artifact.
    - `description` string, nullable
    - `source_kind` string
    - `source_id` string, required — Upstream session id (e.g. Claude sessionId UUID).
    - `captured_by_client` string, nullable
    - `originating_agent` string, nullable
    - `git_remote` string, nullable
    - `git_branch` string, nullable
    - `git_head_sha` string, nullable
    - `git_dirty` boolean, nullable
    - `payload` ScottPushPayload, required — Full structured session capture produced by `scott push`. Source of truth for the TS side is the orval-generated schema (derived from this Pydantic model). Bumped via `schemaVersion` when the parser changes shape.
      - `project` string, required
      - `sessionId` string, required
      - `cwd` string, required
      - `schemaVersion` integer, required
      - `generatedAt` string, required
      - `span` SessionSpan, required
        - `firstTs` string, required
        - `lastTs` string, required
        - `wallClockMs` integer, required
        - `activeMs` integer, required
      - `totals` ScottPushPayloadTotals, required
        - `sessions` integer, required
        - `apiCalls` integer, required
        - `humanMessages` integer, required
        - `usage` TokenUsage, required
          - `inputUncached` integer, required
          - `inputCacheCreate` integer, required
          - `inputCacheRead` integer, required
          - `output` integer, required
          - `total` integer, required
        - `cacheBreaksCount` integer, required
        - `subagentCalls` integer, required
        - `subagentTokens` integer, required
      - `prompts` PromptSummary[]
        - `promptKey` string, required
        - `ts` string, required
        - `slashCommand` string, nullable
        - `text` string, required
        - `apiCalls` integer, required
        - `subagentCalls` integer, required
        - `usage` TokenUsage, required
          - `inputUncached` integer, required
          - `inputCacheCreate` integer, required
          - `inputCacheRead` integer, required
          - `output` integer, required
          - `total` integer, required
        - `context` PromptContextTurn[], required
          - `text` string, required
          - `ts` string, nullable
          - `apiCalls` integer, required
          - `here` boolean, required
      - `subagents` SubagentSummary[]
        - `agentId` string, required
        - `agentType` string, required
        - `parentPromptKey` string, nullable
        - `span` SessionSpan, required
          - `firstTs` string, required
          - `lastTs` string, required
          - `wallClockMs` integer, required
          - `activeMs` integer, required
        - `apiCalls` integer, required
        - `usage` TokenUsage, required
          - `inputUncached` integer, required
          - `inputCacheCreate` integer, required
          - `inputCacheRead` integer, required
          - `output` integer, required
          - `total` integer, required
      - `cacheBreaks` CacheBreak[]
        - `ts` string, required
        - `uncached` integer, required
        - `total` integer, required
        - `promptKey` string, nullable
        - `kind` 'main' | 'subagent', required
        - `agentType` string, nullable
    - `messages` CanonicalMessageSpec[]
      - `role` 'user' | 'assistant', required
      - `content` string, required
      - `fidelity` 'verbatim' | 'paraphrased' | 'summarized', nullable
      - `reconstructed` boolean, nullable
    - `intent` string, nullable
    - `synthesize` boolean
    - `transcript_provenance` 'verbatim' | 'reflected', nullable

## Response `200`

Successful Response

- CreateWorkspaceResponse
  - `workspace_id` string, required
  - `initial_turn_id` string, nullable
  - `final_turn_id` string, nullable
  - `planspace_url` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/tryscott/apis/one-shot-api.md) · [All operations](https://skmtc.dev/tryscott/apis/one-shot-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tryscott/one-shot-api/revisions/28bdface01df/schema)