# Connectors

> The Connectors operations of the Hub REST API (9 operations).

URL: https://docs.synap.live/docs/reference/hub-api/connectors · Generated from Synap-core/backend@c31e261ab (main)

Paths are relative to `/api/hub` on a pod.

## GET /connectors/providers

List available connector providers and connection status

Responses:

- `200`: Provider list
- `503`: Not configured

## GET /connectors/broker-diagnostics

Non-secret trust diagnostics for the connection broker

Responses:

- `200`: Broker trust diagnostics
- `403`: Not a pod owner/admin, or missing scope
- `503`: Diagnostics could not be read

## GET /connectors/sync-status

Sync status per provider × kind × connection

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `provider` | query | string |  |  |
| `workspaceId` | query | string |  |  |

Responses:

- `200`: Sync status rows
- `400`: Bad request — the wrapped door refused the input
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Failed to read sync status

## POST /connectors/connect

Resolve-or-start a connection for a provider (the unified door)

Request body (`application/json`): ConnectorConnectRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `provider` | string |  |  |
| `workspaceId` | string |  |  |
| `onBehalfOfUserId` | string |  |  |
| `forceReauth` | boolean |  |  |

Responses:

- `200`: Connection status: connected \| setup_required \| provider_required \| provider_unavailable
- `400`: Bad request — the wrapped door refused the input
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error
- `503`: Not configured

## POST /connectors/session

Get an OAuth session URL for a specific provider

Request body (`application/json`): ConnectorSessionRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `providerId` | string |  |  |
| `workspaceId` | string |  |  |
| `onBehalfOfUserId` | string |  |  |

Responses:

- `200`: Session URL
- `400`: Bad request — the wrapped door refused the input
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error
- `503`: Not configured

## DELETE /connectors/connections/{connectionId}

Disconnect a specific connection

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `connectionId` | path | string | yes |  |

Responses:

- `200`: Connection revoked
- `400`: Bad request — the wrapped door refused the input
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error
- `503`: Not configured

## POST /connectors/disconnect

Disconnect a connection by connectionId (POST alternative to DELETE)

Request body (`application/json`): DisconnectRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `connectionId` | string | yes |  |
| `provider` | string |  |  |

Responses:

- `200`: Connection revoked
- `400`: Bad request — the wrapped door refused the input
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error
- `503`: Not configured

## GET /connectors/connections/{provider}

List the authenticated user's connections for a specific provider

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `provider` | path | string | yes |  |

Responses:

- `200`: Connection list
- `400`: Bad request — the wrapped door refused the input
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error
- `503`: Nango not configured

## POST /connectors/tool-execute

Execute a provider tool (agnostic connector execution)

Request body (`application/json`): ToolExecuteRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `provider` | string | yes |  |
| `method` | string | yes |  |
| `path` | string | yes |  |
| `body` | object |  |  |
| `accountHint` | string |  |  |
| `baseUrlOverride` | string |  |  |
| `headers` | object |  |  |
| `workspaceId` | string |  |  |
| `agentUserId` | string |  |  |
| `sessionId` | string |  |  |

Responses:

- `200`: Execution result
- `202`: Execution requires human approval — a reviewable proposal was created instead of running.
- `400`: Bad request
- `403`: Forbidden
- `404`: Tool or connection not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error