# 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 <uri>

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 <date-time> | any required
  - Last health probe.
- `revokedAt` string <date-time> | any required
  - When it was disconnected. The credential is purged; the row tombstones.
- `createdAt` string <date-time> required
- `updatedAt` string <date-time> 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 <date-time> required
- `finishedAt` string <date-time>

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