Analyze a source connection

Reads the repository at a ref and returns the build settings to run with, the files that drove detection, other directories that could be the project root, and configuration for other hosts that a Spacefast build cannot honor. Requires the connection’s sync to have reached ready.

POST /v1/spaces/{spaceId}/source/connection/analyze

Authorization

Authorization Bearer token · header required

`Authorization: Bearer ` 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:read

Path parameters

• spaceId string required

Query parameters

• connectionType string required
  default: "connected"
  Allowed: connected hosted

Request body

required application/json

• ref string
  Branch, tag, or commit to inspect. Defaults to the connection's default branch.
  min length 1
• rootDirectory string | any
  Directory to inspect, relative to the repository root. Send null to search the repository for candidate directories instead.

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

• detected object required

Build settings to run with: what the repository suggests, with settings already saved on the connection taking precedence.

• 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
  • detectedFiles string[] required
  • candidates object[] required
  • platformConfigs object[] required
  • unsupportedFeatures string[] required
  • blocked boolean required
  • message string | any required

Example cURL Request

curl -X POST "https://api.spacefast.com/v1/spaces/string/source/connection/analyze?connectionType=connected" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{\n  "ref": "string",\n  "rootDirectory": "string"\n}'

Example JavaScript Fetch

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

Example Python Request

import requests

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

Response Example

{
  "$schema": "http://example.com",
  "data": {
    "detected": {
      "rootDirectory": null,
      "installDirectory": null,
      "installCommand": null,
      "buildCommand": null,
      "outputDirectory": null,
      "ignoredBuildCommand": null,
      "frameworkPreset": null,
      "platformPreset": null,
      "allowUnsupportedPlatformFeatures": false,
      "timeoutSeconds": 900
    },
    "detectedFiles": [
      "string"
    ],
    "candidates": [],
    "platformConfigs": [
      {
        "platform": "vercel",
        "rootDirectory": "string",
        "installDirectory": "string",
        "installCommand": "string",
        "buildCommand": "string",
        "outputDirectory": "string",
        "unsupportedFeatures": [
          "string"
        ]
      }
    ],
    "unsupportedFeatures": [
      "string"
    ],
    "blocked": true,
    "message": "string"
  }
}

Error Response Example

{
  "$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"
}