SynapSynapDocs
Hub REST API

Connectors

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

For BuildersOpen-source podSynap CloudGenerated from Synap-core/backend@c31e261ab (main)

List available connector providers and connection status

GET
/connectors/providers

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Response Body

Provider list

application/json
  1. response
providers*array<>
nangoStatus*string
Value in"ok""error"
nangoError?
Example Request
curl -X GET 'https://pod.example.com/api/hub/connectors/providers'
Example Response
{  "providers": [    {      "id": "string",      "provider": "string",      "displayName": "string",      "connected": true,      "connectionId": "string"    }  ],  "nangoStatus": "ok",  "nangoError": {    "reason": "unreachable",    "message": "string"  }}

Non-secret trust diagnostics for the connection broker

GET
/connectors/broker-diagnostics

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Response Body

Broker trust diagnostics

application/json
  1. response
cpIssuer*
ownerIdentityLink*
relayCredential*
broker*
Example Request
curl -X GET 'https://pod.example.com/api/hub/connectors/broker-diagnostics'
Example Response
{  "cpIssuer": {    "present": true,    "status": "pending",    "hasSourceConfigWrite": true  },  "ownerIdentityLink": {    "present": true  },  "relayCredential": {    "present": true,    "resolvable": true,    "validUntil": "string"  },  "broker": {    "kind": "control-plane",    "reason": "string"  }}

Sync status per provider × kind × connection

GET
/connectors/sync-status

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Query Parameters

provider?string
workspaceId?string

Response Body

Sync status rows

application/json
  1. response
statuses*array<>
Example Request
curl -X GET 'https://pod.example.com/api/hub/connectors/sync-status'
Example Response
{  "statuses": [    {      "provider": "string",      "connectionId": "string",      "workspaceId": "string",      "kind": "string",      "enabled": true,      "profileSlugs": [        "string"      ],      "openableProfileSlugs": [        "string"      ],      "lastRunAt": "string",      "phase": "fetching",      "counts": {        "fetched": 0,        "created": 0,        "merged": 0,        "skipped": 0,        "byProfile": {          "property1": {            "created": 0,            "merged": 0          },          "property2": {            "created": 0,            "merged": 0          }        }      },      "proposalId": "string",      "keepSyncing": {        "enabled": true,        "ruleId": "string",        "available": true      },      "brokerConnectionId": "string",      "connectionState": "needs_reauth",      "error": "string",      "failure": {        "errorClass": "auth",        "enableProposalId": "string",        "resolved": true,        "next": {          "kind": "add",          "hint": "string",          "url": "string"        }      }    }  ]}

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

POST
/connectors/connect

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
provider?string
workspaceId?string
onBehalfOfUserId?string
forceReauth?boolean

Response Body

Connection status: connected | setup_required | provider_required | provider_unavailable

application/json
  1. response
status*string
Value in"connected""setup_required""provider_required""provider_unavailable"
provider?string
displayName?string
code?"POD_PROVIDER_NOT_CONFIGURED"
Value in"POD_PROVIDER_NOT_CONFIGURED"
reason?string
Value in"not_declared""unauthenticated""unreachable""malformed""truncated"
message?string
connectionId?string
redirectUrl?string
sessionToken?string
providers?array<>
unlocked?array<>
Example Request
curl -X POST 'https://pod.example.com/api/hub/connectors/connect' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "status": "connected",  "provider": "string",  "displayName": "string",  "code": "POD_PROVIDER_NOT_CONFIGURED",  "reason": "not_declared",  "message": "string",  "connectionId": "string",  "redirectUrl": "string",  "sessionToken": "string",  "providers": [    {      "id": "string",      "provider": "string",      "displayName": "string",      "connected": true    }  ],  "unlocked": [    {      "provider": "string",      "displayName": "string",      "skills": [        {          "name": "string",          "description": "string"        }      ]    }  ]}

Get an OAuth session URL for a specific provider

POST
/connectors/session

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
providerId?string
workspaceId?string
onBehalfOfUserId?string

Response Body

Session URL

application/json
  1. response
redirectUrl*string
sessionToken*string
Example Request
curl -X POST 'https://pod.example.com/api/hub/connectors/session' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "redirectUrl": "string",  "sessionToken": "string"}

Disconnect a specific connection

DELETE
/connectors/connections/{connectionId}

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

connectionId*string

Response Body

Connection revoked

application/json
  1. response
success*boolean
Example Request
curl -X DELETE 'https://pod.example.com/api/hub/connectors/connections/string'
Example Response
{  "success": true}

Disconnect a connection by connectionId (POST alternative to DELETE)

POST
/connectors/disconnect

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
connectionId*string
provider?string

Response Body

Connection revoked

application/json
  1. response
success*boolean
Example Request
curl -X POST 'https://pod.example.com/api/hub/connectors/disconnect' \  -H 'Content-Type: application/json' \  -d '{  "connectionId": "string"}'
Example Response
{  "success": true}

List the authenticated user's connections for a specific provider

GET
/connectors/connections/{provider}

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

provider*string

Response Body

Connection list

application/json
  1. response
connections*array<>
Example Request
curl -X GET 'https://pod.example.com/api/hub/connectors/connections/string'
Example Response
{  "connections": [    {      "connectionId": "string",      "provider": "string",      "createdAt": "string"    }  ]}

Execute a provider tool (agnostic connector execution)

POST
/connectors/tool-execute

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
provider*string
method*string
path*string
body?
accountHint?string
baseUrlOverride?string
headers?
workspaceId?string
agentUserId?string
sessionId?string

Response Body

Execution result

application/json
  1. response
status*number
headers?
body?unknown
Example Request
curl -X POST 'https://pod.example.com/api/hub/connectors/tool-execute' \  -H 'Content-Type: application/json' \  -d '{  "provider": "string",  "method": "string",  "path": "string"}'
Example Response
{  "status": 0,  "headers": {    "property1": "string",    "property2": "string"  },  "body": null}

Commands

The Commands operations of the Hub REST API (3 operations).

Discord

The Discord operations of the Hub REST API (8 operations).