Update a connection

Renames a connection or replaces the agent-visible note on what it is for. Credentials are immutable: to rotate one, reconnect.

PATCH /v1/connectors/connections/{connectionId}

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: connectors:write

Path parameters

• connectionId string required
  min length 1

Query parameters

• team string
  min length 1 · max length 255

Request body

required application/json

• displayName string
  Replacement label.
  min length 1 · max length 255
• description string | any
  Replacement agent-visible description.

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
  A configured instance of a connector, with a credential the control plane holds and never hands out.

Properties

• id string required
  Connection id (cxn_). This is also the first segment of every tool address it owns.
• connector string required
  Slug of the connector this connection authenticates.
• owner string required
  team is shared with everyone on the team; personal is yours, and only within this team — connecting the same account for another team is another connection. Allowed: team, personal
• displayName string required
  What people call this connection, e.g. "Linear (support)".
• description string | any required
  Agent-visible note on what this connection is for. Shown to models choosing between several.
• status string required
  Derived connection state. Never stored, so it cannot drift from the credential it describes. Allowed: pending_authorization, active, degraded, needs_reauth, revoked
• identityLabel string | any required
  Account label reported by the provider, when it identifies itself. Null until the first successful probe.
• credentialConfigured boolean required
  Whether a usable credential is stored. The credential itself is never returned by any endpoint.
• authMethod string | any required
  Slug of the connector auth method this connection used.
• scopes string[] required
  Scopes actually granted, when the provider reports them.
• isDefault boolean required
  Whether this is the connection an agent gets when it names the connector alone.
• toolCount integer required
  Tools reachable through this connection at the last sync.
  min -9007199254740991 · max 9007199254740991
• createdBy string | any required
  User who connected it; null for first-party connections Spacefast owns.
• lastCheckedAt string | any required
  Last health probe.
• revokedAt string | any required
  When it was disconnected. The credential is purged; the row tombstones.
• createdAt string required
  matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
• updatedAt string required
  matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Error Response

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

Parameters

• connectionId path*
• team query

Body

application/json

• displayName string
  Replacement label.
• description string
  Replacement agent-visible description.

Send

Request

cURL

curl -X PATCH "https://api.spacefast.com/v1/connectors/connections/string" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{\n  "displayName": "string",\n  "description": "string"\n}'

JavaScript

const response = await fetch("https://api.spacefast.com/v1/connectors/connections/string", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"displayName\": \"string\",\n  \"description\": \"string\"\n}"
});

Python

import requests

response = requests.patch(
    "https://api.spacefast.com/v1/connectors/connections/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"displayName\": \"string\",\n  \"description\": \"string\"\n}",
)

Response

200 Default

{
  "$schema": "http://example.com",
  "data": {
    "id": "string",
    "connector": "string",
    "owner": "team",
    "displayName": "string",
    "description": "string",
    "status": "pending_authorization",
    "identityLabel": "string",
    "credentialConfigured": true,
    "authMethod": "string",
    "scopes": [\
      "string"\
    ],
    "isDefault": true,
    "toolCount": -9007199254740991,
    "createdBy": "string",
    "lastCheckedAt": "2019-08-24T14:15:22Z",
    "revokedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

Error 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"
}