Create a repository branch - Spacefast Docs

Create a repository branch

Creates a branch starting from baseRef and returns the commit it points at. For a branch meant to be thrown away after a preview or an agent edit, use the ephemeral-branch operation instead.

POST /v1/spaces/{spaceId}/source/branches

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 · header required

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

Scopes: spaces:write

Path parameters

spaceId string required

Request body

required application/json

connectionType string required

Allowed: connected hosted

branch string required

Name for the new branch.

min length 1

baseRef string

Branch, tag, or commit the new branch starts from. Omit to start from the repository's default branch.

min length 1

Responses

201 Response for status 201

$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

Show properties Hide properties

branch object required

repositoryConnection object required

Source connection ID (rpc_ prefix).

Space this connection feeds.

Git host the repository lives on.

Allowed: github gitlab bitbucket generic

connected for a repository linked from a Git host, hosted for the mirror Spacefast hosts and the caller pushes to.

Allowed: connected hosted

Identifier of the mirror that content reads and builds run against. Null when no mirror is bound yet.

GitHub App installation the connection reads through. Null for a hosted mirror.

default: null

Whether a clone URL is stored. The URL itself is not returned.

default: false

Whether an upstream URL to pull from is stored. The URL itself is not returned.

default: false

Repository name without its owner.

Repository name as owner/name.

Branch the Git host treats as the repository default.

Branch whose pushes produce production builds, and the ref content reads fall back to when none is given.

Whether a Git credential is stored. The credential itself is never returned.

Whether a push to the production branch queues a build.

Whether a push to any other branch or a pull request queues a preview build.

Install, build, and output settings each build runs with.

Show properties Hide properties

Directory the build runs in, relative to the source root. Null builds at the root.

default: null

Directory dependencies install into, relative to the source root. Null installs in the build directory.

default: null

Command that installs dependencies. Null lets the build runner pick one.

default: null

Command that produces the output. Null lets the build runner pick one.

default: null

Directory the built output is collected from, relative to the build directory. Null lets the build runner detect it.

default: null

Command run before the build to decide whether the build is needed. Exiting 0 ends the build as skipped; any other exit code continues. Null always builds.

default: null

Framework the source builds with, for example next or vite. Null lets the build runner detect it.

default: null

Platform build convention the source follows, for example vercel or netlify. Null lets the build runner detect it.

default: null

Runs the build even when the source declares platform features Spacefast does not support. Defaults to false, which refuses those sources.

default: false

Wall-clock budget for the run, in seconds. Between 60 and 7200; defaults to 900.

min 60 · max 7200 · default: 900

idle before the first sync, syncing while one runs, ready once content reads work, failed when the last one did not finish.

Allowed: idle syncing ready failed

Whether the Git host still grants access. Anything other than active blocks builds until the caller reinstalls or reauthorizes.

default: "active"

Allowed: active suspended revoked reauthorization_required

What the Git host reported when access stopped working. Null while access holds.

default: null

ISO 8601 timestamp of the last sync that finished. Null before the first one.

Why the last sync failed. Null after a sync that succeeded.

Identifier of the sync in flight. Null when no sync is running.

User who last authorized or changed the connection. Null when no user did.

ISO 8601 timestamp when the connection was created.

ISO 8601 timestamp of the last change.

repositoryId

string required

defaultError

Every 4xx and 5xx response is one RFC 9457 problem document served as application/problem+json.

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

Try it

Server

Base URL https://api.spacefast.com

Custom base URL

Overrides the selected server when set.

Authorization

Bearer token

Remember on this device

Include my values in samples

Parameters

spaceId path*

Body

application/json

connectionType string* connected hosted

branch string* Name for the new branch.

baseRef string Branch, tag, or commit the new branch starts from. Omit to start from the repository's default branch.

Send

Request

cURL

curl -X POST "https://api.spacefast.com/v1/spaces/string/source/branches" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "connectionType": "connected",
  "branch": "string",
  "baseRef": "string"
}'

JavaScript

const response = await fetch("https://api.spacefast.com/v1/spaces/string/source/branches", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"connectionType\": \"connected\",\n  \"branch\": \"string\",\n  \"baseRef\": \"string\"\n}"
});

Python

import requests

response = requests.post(
    "https://api.spacefast.com/v1/spaces/string/source/branches",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"connectionType\": \"connected\",\n  \"branch\": \"string\",\n  \"baseRef\": \"string\"\n}",
)

Response

{
  "$schema": "http://example.com",
  "data": {
    "branch": {
      "name": "string",
      "commitSha": "string",
      "message": "string"
    },
    "repositoryConnection": {
      "id": "string",
      "spaceId": "string",
      "provider": "github",
      "connectionType": "connected",
      "repositoryId": "string",
      "installationId": null,
      "cloneUrlConfigured": false,
      "upstreamUrlConfigured": false,
      "repositoryName": "string",
      "repositoryFullName": "string",
      "defaultBranch": "string",
      "productionBranch": "string",
      "credentialConfigured": true,
      "autoDeployProduction": true,
      "autoDeployPreviews": true,
      "buildSettings": {
        "rootDirectory": null,
        "installDirectory": null,
        "installCommand": null,
        "buildCommand": null,
        "outputDirectory": null,
        "ignoredBuildCommand": null,
        "frameworkPreset": null,
        "platformPreset": null,
        "allowUnsupportedPlatformFeatures": false,
        "timeoutSeconds": 900
      },
      "syncStatus": "idle",
      "providerAccessStatus": "active",
      "providerAccessError": null,
      "lastSyncedAt": "2019-08-24T14:15:22Z",
      "lastSyncError": "string",
      "syncRunId": "string",
      "connectedUserId": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    },
    "repositoryId": "string"
  }
}

{
  "$schema": "http://example.com",
  "type": "string",
  "title": "string",
  "status": -9007199254740991,
  "detail": "string",
  "code": "string",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [
    "string"
  ],
  "next": [
    "string"
  ],
  "requestId": "string"
}