Re-sync a connection's tools

Re-resolves the tool catalog behind a connection. Token refresh happens on its own; this is about the tools.

Endpoint

POST /v1/connectors/connections/{connectionId}/refresh

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

Minimum length 1

Query parameters

• team string

Minimum length 1 · Maximum length 255

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.
• 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
• updatedAt string required

Operation object required

• Background operation handle when asynchronous work remains after this mutation; null when it completed synchronously.

Properties:

• id string required
• kind string required
• status string required
  • Allowed: queued, running, succeeded, failed, canceled
• resources object[] required
  • Array of object
• progress object
• diagnostics object[]
• createdAt string required
• finishedAt string

Error response

If an error occurs, this is the structure returned:

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