# Create a durable source workspace

Create a workspace without a local checkout. Send a unique operationId in the request body. Reuse that operationId and the exact input after an uncertain response. Read the workspace ID from data.workspace.id in the API response. Use this ID as workspaceId in later requests.

The API uses saved source when it exists. Otherwise, omit originalUploadVersionId to import the current eligible direct upload. Send the field only to pin a known eligible upload. If neither source exists, the API creates an empty baseline. This action does not deploy or change the live version.

## POST `/v1/spaces/{spaceId}/source/workspaces`

### Authorization

`Authorization` Bearer token · header required

`Authorization: Bearer <token>` with an API key (`sfa_` prefix), an OAuth access token, a session token, or a Space machine credential (`sfm_` prefix).

or

`Authorization` OAuth2 access token · header required

OAuth 2.0 with Spacefast scopes. People use the authorization code flow; machines use client credentials.

**Scopes:** `spaces:write` `spaces:read`

### Path parameters

`spaceId` string required

### Request body

required `application/json`

- `operationId` string required

Unique ID for this operation. Reuse this ID and the same input after an uncertain response.
    min length 1 · max length 128

- `name` string

min length 1 · max length 160

- `targetBranch` string

Existing project branch. Defaults to the production branch.
    min length 1 · max length 255

- `originalUploadVersionId` string

Pinned eligible direct upload to import if this Space has no saved source. Omit to import the current eligible direct upload automatically. Never send a build output version.
    min length 1 · max length 64

- `author` object

Omit to use the registered name and email. If they are incomplete, send the author once when you create the workspace. This affects attribution only.
      - `name` string required

min length 1
      - `email` string <email> required

matches ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*[A-Za-z0-9_+-]@[A-Za-z0-9][A-Za-z0-9\-]*\.[A-Za-z]{2,})$

### Responses

**200 Response for status 200**

- `$schema` string <uri>

Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.

- `data` object required

- `workspace` object required

- `id` string required
    - `spaceId` string required
    - `repositoryId` string required
    - `targetBranch` string required
    - `name` string required
    - `revision` integer required

min 0 · max 9007199254740991

- `state` string required

Allowed: `initializing` `active` `conflicted` `closed`

- `baseCommitSha` string | any required
    - `indexCommitSha` string | any required
    - `workingCommitSha` string | any required
    - `headCommitSha` string | any required
    - `originalUploadVersionId` string | any required
    - `hasStagedChanges` boolean required
    - `hasUnstagedChanges` boolean required
    - `hasPendingChanges` boolean required
    - `needsSync` boolean required
    - `pendingOperationId` string | any required
    - `autoDeploy` boolean required
    - `createdAt` string required
    - `updatedAt` string required

- `commit` object

- `sourceCommitSha` string required
    - `parentSourceCommitSha` string required
    - `message` string required
    - `autoDeploy` boolean required

- `conflicts` object

- `phase` string required

Allowed: `staged` `working` `undo`

- `labels` object required

- `ours` string required
      - `theirs` string required

- `files` object[] required

Array of `object`

- `path` string required
        - `result` string required
        - `base` object required

- `sourceCommitSha` string required
            - `content` string | any required
            - `exists` boolean required
            - `binary` boolean required
            - `truncated` boolean required

- `ours` object required

- `sourceCommitSha` string required
            - `content` string | any required
            - `exists` boolean required
            - `binary` boolean required
            - `truncated` boolean required

- `theirs` object required

- `sourceCommitSha` string required
            - `content` string | any required
            - `exists` boolean required
            - `binary` boolean required
            - `truncated` boolean required

### Example requests

#### cURL Example

```bash
curl -X POST "https://api.spacefast.com/v1/spaces/string/source/workspaces" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operationId": "string",
  "name": "string",
  "targetBranch": "string",
  "originalUploadVersionId": "string",
  "author": {
    "name": "string",
    "email": "user@example.com"
  }
}'
```

#### JavaScript Example

```javascript
const response = await fetch("https://api.spacefast.com/v1/spaces/string/source/workspaces", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"operationId\": \"string\",\n  \"name\": \"string\",\n  \"targetBranch\": \"string\",\n  \"originalUploadVersionId\": \"string\",\n  \"author\": {\n    \"name\": \"string\",\n    \"email\": \"user@example.com\"\n  }\n}"
});
```

#### Python Example

```python
import requests

response = requests.post(
    "https://api.spacefast.com/v1/spaces/string/source/workspaces",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"operationId\": \"string\",\n  \"name\": \"string\",\n  \"targetBranch\": \"string\",\n  \"originalUploadVersionId\": \"string\",\n  \"author\": {\n    \"name\": \"string\",\n    \"email\": \"user@example.com\"\n  }\n}",
)
```

### Error Responses

**Default Problem details (RFC 9457). Any 4xx/5xx response is one `application/problem+json` document.**

- `$schema` string <uri>

Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.

- `type` string required

URL of the documentation page for this error. Derived from `code`.

- `title` string required

Human-readable name of the error type. Derived from `code`.

- `status` integer required

HTTP status of the response, repeated in the body.

min -9007199254740991 · max 9007199254740991

- `detail` string required

What went wrong in this request.

- `code` string required

Stable snake_case error code. Match on this, not on `detail`.

- `pointer` string

RFC 6901 JSON Pointer to the request field or batch entry that failed, for example `/files/37/path`. Present on validation failures.

- `details` object

Machine-readable context keyed by the error code.

- `suggestions` string[]

Recovery steps safe to show to a person.

- `next` string[]

Commands or API requests to run next, usable as written.

- `requestId` string required

ID of this request, from the `X-Request-Id` header or generated. Quote it when contacting support.