Create an ephemeral repository branch

Create a short-lived repository branch for previews, experiments, and agent edits.

Endpoint

POST /v1/spaces/{spaceId}/source/ephemeral-branch

Authorization

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 with Spacefast scopes. People use the authorization code flow; machines use client credentials.

Scopes: spaces:write

Path parameters

• spaceId: string (required)

Query parameters

• connectionType: string (required)
  • Default: "connected"
  • Allowed: connected, hosted

Request body

Required: application/json

• branch: string (required)
  • Name for the short-lived branch. Minimum length 1.
• baseRef: string (optional)
  • Branch, tag, or commit the branch starts from. Minimum length 1.
• baseBranch: string (optional)
  • Branch the branch starts from, when the start point is a branch. Minimum length 1.
• ttlSeconds: integer (optional)
  • How long the signed access lasts, in seconds. At most 86400.
• readOnlyRefs: string[] (optional)
  • Refs the access may read but never write. At most 25.

Responses

201 Response for status 201

• $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)

• repositoryConnection: object (required)

  • id: string (required)
  • spaceId: string (required)
  • provider: string (required)
    • Allowed: github, gitlab, bitbucket, generic
  • connectionType: string (required)
    • connected or hosted
  • repositoryId: string | any (required)
  • installationId: string | any (required)
  • cloneUrlConfigured: boolean (required)
  • upstreamUrlConfigured: boolean (required)
  • repositoryName: string (required)
  • repositoryFullName: string (required)
  • defaultBranch: string (required)
  • productionBranch: string (required)
  • credentialConfigured: boolean (required)
  • autoDeployProduction: boolean (required)
  • autoDeployPreviews: boolean (required)
  • buildSettings: object (required)
    • rootDirectory: string | any (required)
    • installDirectory: string | any (required)
    • installCommand: string | any (required)
    • buildCommand: string | any (required)
    • outputDirectory: string | any (required)
    • ignoredBuildCommand: string | any (required)
    • frameworkPreset: string | any (required)
    • platformPreset: string | any (required)
    • allowUnsupportedPlatformFeatures: boolean (required)
    • timeoutSeconds: integer (required)
  • syncStatus: string (required)
  • providerAccessStatus: string (required)
  • providerAccessError: string | any (required)
  • lastSyncedAt: string (required)
  • lastSyncError: string | any (required)
  • syncRunId: string | any (required)
  • connectedUserId: string | any (required)
  • createdAt: string (required)
  • updatedAt: string (required)

• branch: object (required)

  • repositoryId: string (required)
  • branch: string (required)
  • baseRef: string | any (required)
  • baseBranch: string | any (required)
  • ephemeral: boolean (required)