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 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

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

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

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

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

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.